Chromium Code Reviews| 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 * |
| 11 * Usage: | 11 * Usage: |
| 12 * | 12 * |
| 13 * $ dart apidoc.dart [--out=<output directory>] | 13 * $ dart apidoc.dart [--out=<output directory>] |
| 14 */ | 14 */ |
| 15 library apidoc; | 15 library apidoc; |
| 16 | 16 |
| 17 import 'dart:async'; | 17 import 'dart:async'; |
| 18 import 'dart:io'; | 18 import 'dart:io'; |
| 19 import 'dart:json' as json; | 19 import 'dart:json' as json; |
| 20 import 'dart:uri'; | |
| 20 | 21 |
| 21 import 'html_diff.dart'; | 22 import 'html_diff.dart'; |
| 22 | 23 |
| 23 // TODO(rnystrom): Use "package:" URL (#4968). | 24 // TODO(rnystrom): Use "package:" URL (#4968). |
| 24 import '../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors.dart'; | 25 import '../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors.dart'; |
| 25 import '../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dar t'; | 26 import '../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dar t'; |
| 27 import '../../sdk/lib/_internal/compiler/implementation/filenames.dart'; | |
| 26 import '../../sdk/lib/_internal/dartdoc/lib/dartdoc.dart'; | 28 import '../../sdk/lib/_internal/dartdoc/lib/dartdoc.dart'; |
| 27 import '../../sdk/lib/_internal/libraries.dart'; | 29 import '../../sdk/lib/_internal/libraries.dart'; |
| 28 | 30 |
| 29 HtmlDiff _diff; | 31 HtmlDiff _diff; |
| 30 | 32 |
| 31 void main() { | 33 void main() { |
| 32 final args = new Options().arguments; | 34 final args = new Options().arguments; |
| 33 | 35 |
| 34 int mode = MODE_STATIC; | 36 int mode = MODE_STATIC; |
| 35 Path outputDir = new Path('docs'); | 37 Path outputDir = new Path('docs'); |
| (...skipping 56 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
| 92 outputDir); | 94 outputDir); |
| 93 | 95 |
| 94 print('Parsing MDN data...'); | 96 print('Parsing MDN data...'); |
| 95 final mdnFile = new File.fromPath(scriptDir.append('mdn/database.json')); | 97 final mdnFile = new File.fromPath(scriptDir.append('mdn/database.json')); |
| 96 final mdn = json.parse(mdnFile.readAsStringSync()); | 98 final mdn = json.parse(mdnFile.readAsStringSync()); |
| 97 | 99 |
| 98 print('Cross-referencing dart:html...'); | 100 print('Cross-referencing dart:html...'); |
| 99 // TODO(amouravski): move HtmlDiff inside of the future chain below to re-use | 101 // TODO(amouravski): move HtmlDiff inside of the future chain below to re-use |
| 100 // the MirrorSystem already analyzed. | 102 // the MirrorSystem already analyzed. |
| 101 _diff = new HtmlDiff(printWarnings:false); | 103 _diff = new HtmlDiff(printWarnings:false); |
| 102 Future htmlDiff = _diff.run(libPath); | 104 Future htmlDiff = _diff.run(currentDirectory.resolve(libPath.toString())); |
| 103 | 105 |
| 104 // TODO(johnniwinther): Libraries for the compilation seem to be more like | 106 // TODO(johnniwinther): Libraries for the compilation seem to be more like |
| 105 // URIs. Perhaps Path should have a toURI() method. | 107 // URIs. Perhaps Path should have a toURI() method. |
| 106 // Add all of the core libraries. | 108 // Add all of the core libraries. |
| 107 final apidocLibraries = <Path>[]; | 109 final apidocLibraries = <Path>[]; |
| 108 LIBRARIES.forEach((String name, LibraryInfo info) { | 110 LIBRARIES.forEach((String name, LibraryInfo info) { |
| 109 if (info.documented) { | 111 if (info.documented) { |
| 110 apidocLibraries.add(new Path('dart:$name')); | 112 apidocLibraries.add(new Path('dart:$name')); |
| 111 } | 113 } |
| 112 }); | 114 }); |
| (...skipping 229 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
| 342 /** | 344 /** |
| 343 * Gets the MDN-scraped docs for [type], or `null` if this type isn't | 345 * Gets the MDN-scraped docs for [type], or `null` if this type isn't |
| 344 * scraped from MDN. | 346 * scraped from MDN. |
| 345 */ | 347 */ |
| 346 MdnComment includeMdnTypeComment(TypeMirror type) { | 348 MdnComment includeMdnTypeComment(TypeMirror type) { |
| 347 if (_mdnTypeNamesToSkip.contains(type.simpleName)) { | 349 if (_mdnTypeNamesToSkip.contains(type.simpleName)) { |
| 348 return null; | 350 return null; |
| 349 } | 351 } |
| 350 | 352 |
| 351 var typeString = ''; | 353 var typeString = ''; |
| 352 if (HTML_LIBRARY_NAMES.contains(displayName(type.library))) { | 354 if (HTML_LIBRARY_URIS.contains(type.library.uri)) { |
| 353 // If it's an HTML type, try to map it to a base DOM type so we can find | 355 // If it's an HTML type, try to map it to a base DOM type so we can find |
| 354 // the MDN docs. | 356 // the MDN docs. |
| 355 final domTypes = _diff.htmlTypesToDom[type.qualifiedName]; | 357 final domTypes = _diff.htmlTypesToDom[type.qualifiedName]; |
| 356 | 358 |
| 357 // Couldn't find a DOM type. | 359 // Couldn't find a DOM type. |
| 358 if ((domTypes == null) || (domTypes.length != 1)) return null; | 360 if ((domTypes == null) || (domTypes.length != 1)) return null; |
| 359 | 361 |
| 360 // Use the corresponding DOM type when searching MDN. | 362 // Use the corresponding DOM type when searching MDN. |
| 361 // TODO(rnystrom): Shame there isn't a simpler way to get the one item | 363 // TODO(rnystrom): Shame there isn't a simpler way to get the one item |
| 362 // out of a singleton Set. | 364 // out of a singleton Set. |
| (...skipping 16 matching lines...) Expand all Loading... | |
| 379 return new MdnComment(mdnType['summary'], mdnType['srcUrl']); | 381 return new MdnComment(mdnType['summary'], mdnType['srcUrl']); |
| 380 } | 382 } |
| 381 | 383 |
| 382 /** | 384 /** |
| 383 * Gets the MDN-scraped docs for [member], or `null` if this type isn't | 385 * Gets the MDN-scraped docs for [member], or `null` if this type isn't |
| 384 * scraped from MDN. | 386 * scraped from MDN. |
| 385 */ | 387 */ |
| 386 MdnComment includeMdnMemberComment(MemberMirror member) { | 388 MdnComment includeMdnMemberComment(MemberMirror member) { |
| 387 var library = findLibrary(member); | 389 var library = findLibrary(member); |
| 388 var memberString = ''; | 390 var memberString = ''; |
| 389 if (HTML_LIBRARY_NAMES.contains(displayName(library))) { | 391 if (HTML_LIBRARY_URIS.contains(library.uri)) { |
| 390 // If it's an HTML type, try to map it to a DOM type name so we can find | 392 // If it's an HTML type, try to map it to a DOM type name so we can find |
| 391 // the MDN docs. | 393 // the MDN docs. |
| 392 final domMembers = _diff.htmlToDom[member.qualifiedName]; | 394 final domMembers = _diff.htmlToDom[member.qualifiedName]; |
| 393 | 395 |
| 394 // Couldn't find a DOM type. | 396 // Couldn't find a DOM type. |
| 395 if ((domMembers == null) || (domMembers.length != 1)) return null; | 397 if ((domMembers == null) || (domMembers.length != 1)) return null; |
| 396 | 398 |
| 397 // Use the corresponding DOM member when searching MDN. | 399 // Use the corresponding DOM member when searching MDN. |
| 398 // TODO(rnystrom): Shame there isn't a simpler way to get the one item | 400 // TODO(rnystrom): Shame there isn't a simpler way to get the one item |
| 399 // out of a singleton Set. | 401 // out of a singleton Set. |
| (...skipping 32 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
| 432 return new MdnComment(mdnMember['help'], mdnType['srcUrl']); | 434 return new MdnComment(mdnMember['help'], mdnType['srcUrl']); |
| 433 } | 435 } |
| 434 | 436 |
| 435 /** | 437 /** |
| 436 * Returns a link to [member], relative to a type page that may be in a | 438 * Returns a link to [member], relative to a type page that may be in a |
| 437 * different library than [member]. | 439 * different library than [member]. |
| 438 */ | 440 */ |
| 439 String _linkMember(MemberMirror member) { | 441 String _linkMember(MemberMirror member) { |
| 440 final typeName = member.owner.simpleName; | 442 final typeName = member.owner.simpleName; |
| 441 var memberName = '$typeName.${member.simpleName}'; | 443 var memberName = '$typeName.${member.simpleName}'; |
| 442 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { | 444 if (member is MethodMirror && member.isConstructor) { |
|
Johnni Winther
2013/04/08 13:22:33
isFactory should have been isFactoryConstructor wh
| |
| 443 final separator = member.constructorName == '' ? '' : '.'; | 445 final separator = member.constructorName == '' ? '' : '.'; |
| 444 memberName = 'new $typeName$separator${member.constructorName}'; | 446 memberName = 'new $typeName$separator${member.constructorName}'; |
| 445 } | 447 } |
| 446 | 448 |
| 447 return a(memberUrl(member), memberName); | 449 return a(memberUrl(member), memberName); |
| 448 } | 450 } |
| 449 } | 451 } |
| OLD | NEW |