| OLD | NEW |
| 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
| 2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
| 3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
| 4 | 4 |
| 5 /** | 5 /** |
| 6 * This generates the reference documentation for the core libraries that come | 6 * This generates the reference documentation for the core libraries that come |
| 7 * with dart. It is built on top of dartdoc, which is a general-purpose library | 7 * with dart. It is built on top of dartdoc, which is a general-purpose library |
| 8 * for generating docs from any Dart code. This library extends that to include | 8 * for generating docs from any Dart code. This library extends that to include |
| 9 * additional information and styling specific to our standard library. | 9 * additional information and styling specific to our standard library. |
| 10 * | 10 * |
| (...skipping 139 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 150 } | 150 } |
| 151 | 151 |
| 152 // Suppress any actual writing to file. This is only for analysis. | 152 // Suppress any actual writing to file. This is only for analysis. |
| 153 void endFile() { | 153 void endFile() { |
| 154 } | 154 } |
| 155 | 155 |
| 156 void write(String s) { | 156 void write(String s) { |
| 157 } | 157 } |
| 158 | 158 |
| 159 String getRecordedLibraryComment(LibraryMirror library) { | 159 String getRecordedLibraryComment(LibraryMirror library) { |
| 160 if (library.simpleName() == HTML_LIBRARY_NAME) { | 160 if (library.simpleName == HTML_LIBRARY_NAME) { |
| 161 return libraryComment; | 161 return libraryComment; |
| 162 } | 162 } |
| 163 return null; | 163 return null; |
| 164 } | 164 } |
| 165 | 165 |
| 166 String getRecordedTypeComment(TypeMirror type) { | 166 String getRecordedTypeComment(TypeMirror type) { |
| 167 if (typeComments.containsKey(type.qualifiedName())) { | 167 if (typeComments.containsKey(type.qualifiedName)) { |
| 168 return typeComments[type.qualifiedName()]; | 168 return typeComments[type.qualifiedName]; |
| 169 } | 169 } |
| 170 return null; | 170 return null; |
| 171 } | 171 } |
| 172 | 172 |
| 173 String getRecordedMemberComment(MemberMirror member) { | 173 String getRecordedMemberComment(MemberMirror member) { |
| 174 if (memberComments.containsKey(member.qualifiedName())) { | 174 if (memberComments.containsKey(member.qualifiedName)) { |
| 175 return memberComments[member.qualifiedName()]; | 175 return memberComments[member.qualifiedName]; |
| 176 } | 176 } |
| 177 return null; | 177 return null; |
| 178 } | 178 } |
| 179 | 179 |
| 180 // These methods are subclassed and used for internal processing. | 180 // These methods are subclassed and used for internal processing. |
| 181 // Do not invoke outside of this class. | 181 // Do not invoke outside of this class. |
| 182 String getLibraryComment(LibraryMirror library) { | 182 String getLibraryComment(LibraryMirror library) { |
| 183 String comment = super.getLibraryComment(library); | 183 String comment = super.getLibraryComment(library); |
| 184 libraryComment = comment; | 184 libraryComment = comment; |
| 185 return comment; | 185 return comment; |
| (...skipping 15 matching lines...) Expand all Loading... |
| 201 String comment = super.getFieldComment(field); | 201 String comment = super.getFieldComment(field); |
| 202 recordMemberComment(field, comment); | 202 recordMemberComment(field, comment); |
| 203 return comment; | 203 return comment; |
| 204 } | 204 } |
| 205 | 205 |
| 206 void recordTypeComment(TypeMirror type, String comment) { | 206 void recordTypeComment(TypeMirror type, String comment) { |
| 207 if (comment != null && comment.contains('@domName')) { | 207 if (comment != null && comment.contains('@domName')) { |
| 208 // This is not a handwritten comment. | 208 // This is not a handwritten comment. |
| 209 return; | 209 return; |
| 210 } | 210 } |
| 211 typeComments[type.qualifiedName()] = comment; | 211 typeComments[type.qualifiedName] = comment; |
| 212 } | 212 } |
| 213 | 213 |
| 214 void recordMemberComment(MemberMirror member, String comment) { | 214 void recordMemberComment(MemberMirror member, String comment) { |
| 215 if (comment != null && comment.contains('@domName')) { | 215 if (comment != null && comment.contains('@domName')) { |
| 216 // This is not a handwritten comment. | 216 // This is not a handwritten comment. |
| 217 return; | 217 return; |
| 218 } | 218 } |
| 219 memberComments[member.qualifiedName()] = comment; | 219 memberComments[member.qualifiedName] = comment; |
| 220 } | 220 } |
| 221 } | 221 } |
| 222 | 222 |
| 223 class Apidoc extends doc.Dartdoc { | 223 class Apidoc extends doc.Dartdoc { |
| 224 /** Big ball of JSON containing the scraped MDN documentation. */ | 224 /** Big ball of JSON containing the scraped MDN documentation. */ |
| 225 final Map mdn; | 225 final Map mdn; |
| 226 | 226 |
| 227 final Htmldoc htmldoc; | 227 final Htmldoc htmldoc; |
| 228 | 228 |
| 229 static final disqusShortname = 'dartapidocs'; | 229 static final disqusShortname = 'dartapidocs'; |
| (...skipping 87 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 317 var s = document.getElementsByTagName("script")[0]; | 317 var s = document.getElementsByTagName("script")[0]; |
| 318 s.parentNode.insertBefore(ga, s); | 318 s.parentNode.insertBefore(ga, s); |
| 319 })(); | 319 })(); |
| 320 </script> | 320 </script> |
| 321 '''); | 321 '''); |
| 322 } | 322 } |
| 323 | 323 |
| 324 void docIndexLibrary(LibraryMirror library) { | 324 void docIndexLibrary(LibraryMirror library) { |
| 325 // TODO(rnystrom): Hackish. The IO libraries reference this but we don't | 325 // TODO(rnystrom): Hackish. The IO libraries reference this but we don't |
| 326 // want it in the docs. | 326 // want it in the docs. |
| 327 if (library.simpleName() == 'dart:nativewrappers') return; | 327 if (library.simpleName == 'dart:nativewrappers') return; |
| 328 super.docIndexLibrary(library); | 328 super.docIndexLibrary(library); |
| 329 } | 329 } |
| 330 | 330 |
| 331 void docLibraryNavigationJson(LibraryMirror library, Map libraryMap) { | 331 void docLibraryNavigationJson(LibraryMirror library, Map libraryMap) { |
| 332 // TODO(rnystrom): Hackish. The IO libraries reference this but we don't | 332 // TODO(rnystrom): Hackish. The IO libraries reference this but we don't |
| 333 // want it in the docs. | 333 // want it in the docs. |
| 334 if (library.simpleName() == 'dart:nativewrappers') return; | 334 if (library.simpleName == 'dart:nativewrappers') return; |
| 335 super.docLibraryNavigationJson(library, libraryMap); | 335 super.docLibraryNavigationJson(library, libraryMap); |
| 336 } | 336 } |
| 337 | 337 |
| 338 void docLibrary(LibraryMirror library) { | 338 void docLibrary(LibraryMirror library) { |
| 339 // TODO(rnystrom): Hackish. The IO libraries reference this but we don't | 339 // TODO(rnystrom): Hackish. The IO libraries reference this but we don't |
| 340 // want it in the docs. | 340 // want it in the docs. |
| 341 if (library.simpleName() == 'dart:nativewrappers') return; | 341 if (library.simpleName == 'dart:nativewrappers') return; |
| 342 super.docLibrary(library); | 342 super.docLibrary(library); |
| 343 } | 343 } |
| 344 | 344 |
| 345 /** Override definition from parent class to strip out annotation tags. */ | 345 /** Override definition from parent class to strip out annotation tags. */ |
| 346 String commentToHtml(String comment) { | 346 String commentToHtml(String comment) { |
| 347 return super.commentToHtml( | 347 return super.commentToHtml( |
| 348 comment.replaceAll(const RegExp("@([a-zA-Z]+) ([^;]+)(?:;|\$)"), '')); | 348 comment.replaceAll(const RegExp("@([a-zA-Z]+) ([^;]+)(?:;|\$)"), '')); |
| 349 } | 349 } |
| 350 | 350 |
| 351 String getLibraryComment(LibraryMirror library) { | 351 String getLibraryComment(LibraryMirror library) { |
| 352 if (library.simpleName() == HTML_LIBRARY_NAME) { | 352 if (library.simpleName == HTML_LIBRARY_NAME) { |
| 353 return htmldoc.libraryComment; | 353 return htmldoc.libraryComment; |
| 354 } | 354 } |
| 355 return super.getLibraryComment(library); | 355 return super.getLibraryComment(library); |
| 356 } | 356 } |
| 357 | 357 |
| 358 String getTypeComment(TypeMirror type) { | 358 String getTypeComment(TypeMirror type) { |
| 359 return _mergeDocs( | 359 return _mergeDocs( |
| 360 includeMdnTypeComment(type), super.getTypeComment(type), | 360 includeMdnTypeComment(type), super.getTypeComment(type), |
| 361 htmldoc.getRecordedTypeComment(type)); | 361 htmldoc.getRecordedTypeComment(type)); |
| 362 } | 362 } |
| (...skipping 67 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 430 </p> | 430 </p> |
| 431 '''); | 431 '''); |
| 432 } | 432 } |
| 433 } | 433 } |
| 434 | 434 |
| 435 /** | 435 /** |
| 436 * Gets the MDN-scraped docs for [type], or `null` if this type isn't | 436 * Gets the MDN-scraped docs for [type], or `null` if this type isn't |
| 437 * scraped from MDN. | 437 * scraped from MDN. |
| 438 */ | 438 */ |
| 439 includeMdnTypeComment(TypeMirror type) { | 439 includeMdnTypeComment(TypeMirror type) { |
| 440 if (type.library().simpleName() == HTML_LIBRARY_NAME) { | 440 if (type.library.simpleName == HTML_LIBRARY_NAME) { |
| 441 // If it's an HTML type, try to map it to a base DOM type so we can find | 441 // If it's an HTML type, try to map it to a base DOM type so we can find |
| 442 // the MDN docs. | 442 // the MDN docs. |
| 443 final domTypes = _diff.htmlTypesToDom[type.qualifiedName()]; | 443 final domTypes = _diff.htmlTypesToDom[type.qualifiedName]; |
| 444 | 444 |
| 445 // Couldn't find a DOM type. | 445 // Couldn't find a DOM type. |
| 446 if ((domTypes == null) || (domTypes.length != 1)) return null; | 446 if ((domTypes == null) || (domTypes.length != 1)) return null; |
| 447 | 447 |
| 448 // Use the corresponding DOM type when searching MDN. | 448 // Use the corresponding DOM type when searching MDN. |
| 449 // TODO(rnystrom): Shame there isn't a simpler way to get the one item | 449 // TODO(rnystrom): Shame there isn't a simpler way to get the one item |
| 450 // out of a singleton Set. | 450 // out of a singleton Set. |
| 451 type = domTypes.iterator().next(); | 451 type = domTypes.iterator().next(); |
| 452 } else if (type.library().simpleName() != DOM_LIBRARY_NAME) { | 452 } else if (type.library.simpleName != DOM_LIBRARY_NAME) { |
| 453 // Not a DOM type. | 453 // Not a DOM type. |
| 454 return null; | 454 return null; |
| 455 } | 455 } |
| 456 | 456 |
| 457 final mdnType = mdn[type.simpleName()]; | 457 final mdnType = mdn[type.simpleName]; |
| 458 if (mdnType == null) return null; | 458 if (mdnType == null) return null; |
| 459 if (mdnType['skipped'] != null) return null; | 459 if (mdnType['skipped'] != null) return null; |
| 460 | 460 |
| 461 // Remember which MDN page we're using so we can attribute it. | 461 // Remember which MDN page we're using so we can attribute it. |
| 462 mdnUrl = mdnType['srcUrl']; | 462 mdnUrl = mdnType['srcUrl']; |
| 463 return mdnType['summary']; | 463 return mdnType['summary']; |
| 464 } | 464 } |
| 465 | 465 |
| 466 /** | 466 /** |
| 467 * Gets the MDN-scraped docs for [member], or `null` if this type isn't | 467 * Gets the MDN-scraped docs for [member], or `null` if this type isn't |
| 468 * scraped from MDN. | 468 * scraped from MDN. |
| 469 */ | 469 */ |
| 470 includeMdnMemberComment(MemberMirror member) { | 470 includeMdnMemberComment(MemberMirror member) { |
| 471 var library = findLibrary(member); | 471 var library = findLibrary(member); |
| 472 if (library.simpleName() == HTML_LIBRARY_NAME) { | 472 if (library.simpleName == HTML_LIBRARY_NAME) { |
| 473 // If it's an HTML type, try to map it to a base DOM type so we can find | 473 // If it's an HTML type, try to map it to a base DOM type so we can find |
| 474 // the MDN docs. | 474 // the MDN docs. |
| 475 final domMembers = _diff.htmlToDom[member.qualifiedName()]; | 475 final domMembers = _diff.htmlToDom[member.qualifiedName]; |
| 476 | 476 |
| 477 // Couldn't find a DOM type. | 477 // Couldn't find a DOM type. |
| 478 if ((domMembers == null) || (domMembers.length != 1)) return null; | 478 if ((domMembers == null) || (domMembers.length != 1)) return null; |
| 479 | 479 |
| 480 // Use the corresponding DOM member when searching MDN. | 480 // Use the corresponding DOM member when searching MDN. |
| 481 // TODO(rnystrom): Shame there isn't a simpler way to get the one item | 481 // TODO(rnystrom): Shame there isn't a simpler way to get the one item |
| 482 // out of a singleton Set. | 482 // out of a singleton Set. |
| 483 member = domMembers.iterator().next(); | 483 member = domMembers.iterator().next(); |
| 484 } else if (library.simpleName() != DOM_LIBRARY_NAME) { | 484 } else if (library.simpleName != DOM_LIBRARY_NAME) { |
| 485 // Not a DOM type. | 485 // Not a DOM type. |
| 486 return null; | 486 return null; |
| 487 } | 487 } |
| 488 | 488 |
| 489 // Ignore top-level functions. | 489 // Ignore top-level functions. |
| 490 if (member.isTopLevel) return null; | 490 if (member.isTopLevel) return null; |
| 491 | 491 |
| 492 final mdnType = mdn[member.surroundingDeclaration().simpleName()]; | 492 final mdnType = mdn[member.surroundingDeclaration.simpleName]; |
| 493 if (mdnType == null) return null; | 493 if (mdnType == null) return null; |
| 494 var nameToFind = member.simpleName(); | 494 var nameToFind = member.simpleName; |
| 495 var mdnMember = null; | 495 var mdnMember = null; |
| 496 for (final candidateMember in mdnType['members']) { | 496 for (final candidateMember in mdnType['members']) { |
| 497 if (candidateMember['name'] == nameToFind) { | 497 if (candidateMember['name'] == nameToFind) { |
| 498 mdnMember = candidateMember; | 498 mdnMember = candidateMember; |
| 499 break; | 499 break; |
| 500 } | 500 } |
| 501 } | 501 } |
| 502 | 502 |
| 503 if (mdnMember == null) return null; | 503 if (mdnMember == null) return null; |
| 504 | 504 |
| 505 // Remember which MDN page we're using so we can attribute it. | 505 // Remember which MDN page we're using so we can attribute it. |
| 506 mdnUrl = mdnType['srcUrl']; | 506 mdnUrl = mdnType['srcUrl']; |
| 507 return mdnMember['help']; | 507 return mdnMember['help']; |
| 508 } | 508 } |
| 509 | 509 |
| 510 /** | 510 /** |
| 511 * Returns a link to [member], relative to a type page that may be in a | 511 * Returns a link to [member], relative to a type page that may be in a |
| 512 * different library than [member]. | 512 * different library than [member]. |
| 513 */ | 513 */ |
| 514 String _linkMember(MemberMirror member) { | 514 String _linkMember(MemberMirror member) { |
| 515 final typeName = member.surroundingDeclaration().simpleName(); | 515 final typeName = member.surroundingDeclaration.simpleName; |
| 516 var memberName = '$typeName.${member.simpleName()}'; | 516 var memberName = '$typeName.${member.simpleName}'; |
| 517 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { | 517 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { |
| 518 final separator = member.constructorName == '' ? '' : '.'; | 518 final separator = member.constructorName == '' ? '' : '.'; |
| 519 memberName = 'new $typeName$separator${member.constructorName}'; | 519 memberName = 'new $typeName$separator${member.constructorName}'; |
| 520 } | 520 } |
| 521 | 521 |
| 522 return a(memberUrl(member), memberName); | 522 return a(memberUrl(member), memberName); |
| 523 } | 523 } |
| 524 } | 524 } |
| OLD | NEW |