| 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'; | |
| 21 | 20 |
| 22 import 'html_diff.dart'; | 21 import 'html_diff.dart'; |
| 23 | 22 |
| 24 // TODO(rnystrom): Use "package:" URL (#4968). | 23 // TODO(rnystrom): Use "package:" URL (#4968). |
| 25 import '../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors.dart'; | 24 import '../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors.dart'; |
| 26 import '../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dar
t'; | 25 import '../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dar
t'; |
| 27 import '../../sdk/lib/_internal/dartdoc/lib/dartdoc.dart'; | 26 import '../../sdk/lib/_internal/dartdoc/lib/dartdoc.dart'; |
| 28 import '../../sdk/lib/_internal/libraries.dart'; | 27 import '../../sdk/lib/_internal/libraries.dart'; |
| 29 import 'package:pathos/path.dart' as pathos; | |
| 30 | 28 |
| 31 HtmlDiff _diff; | 29 HtmlDiff _diff; |
| 32 | 30 |
| 33 void main() { | 31 void main() { |
| 34 final args = new Options().arguments; | 32 final args = new Options().arguments; |
| 35 | 33 |
| 36 int mode = MODE_STATIC; | 34 int mode = MODE_STATIC; |
| 37 Path outputDir = new Path('docs'); | 35 Path outputDir = new Path('docs'); |
| 38 bool generateAppCache = false; | 36 bool generateAppCache = false; |
| 39 | 37 |
| 40 List<String> excludedLibraries = <String>[]; | 38 List<String> excludedLibraries = <String>[]; |
| 41 List<String> includedLibraries = <String>[]; | 39 List<String> includedLibraries = <String>[]; |
| 42 String packageRoot; | 40 Path packageRoot; |
| 43 String version; | 41 String version; |
| 44 | 42 |
| 45 // Parse the command-line arguments. | 43 // Parse the command-line arguments. |
| 46 for (int i = 0; i < args.length; i++) { | 44 for (int i = 0; i < args.length; i++) { |
| 47 final arg = args[i]; | 45 final arg = args[i]; |
| 48 | 46 |
| 49 switch (arg) { | 47 switch (arg) { |
| 50 case '--mode=static': | 48 case '--mode=static': |
| 51 mode = MODE_STATIC; | 49 mode = MODE_STATIC; |
| 52 break; | 50 break; |
| 53 | 51 |
| 54 case '--mode=live-nav': | 52 case '--mode=live-nav': |
| 55 mode = MODE_LIVE_NAV; | 53 mode = MODE_LIVE_NAV; |
| 56 break; | 54 break; |
| 57 | 55 |
| 58 case '--generate-app-cache=true': | 56 case '--generate-app-cache=true': |
| 59 generateAppCache = true; | 57 generateAppCache = true; |
| 60 break; | 58 break; |
| 61 | 59 |
| 62 default: | 60 default: |
| 63 if (arg.startsWith('--exclude-lib=')) { | 61 if (arg.startsWith('--exclude-lib=')) { |
| 64 excludedLibraries.add(arg.substring('--exclude-lib='.length)); | 62 excludedLibraries.add(arg.substring('--exclude-lib='.length)); |
| 65 } else if (arg.startsWith('--include-lib=')) { | 63 } else if (arg.startsWith('--include-lib=')) { |
| 66 includedLibraries.add(arg.substring('--include-lib='.length)); | 64 includedLibraries.add(arg.substring('--include-lib='.length)); |
| 67 } else if (arg.startsWith('--out=')) { | 65 } else if (arg.startsWith('--out=')) { |
| 68 outputDir = new Path(arg.substring('--out='.length)); | 66 outputDir = new Path(arg.substring('--out='.length)); |
| 69 } else if (arg.startsWith('--package-root=')) { | 67 } else if (arg.startsWith('--package-root=')) { |
| 70 packageRoot = arg.substring('--package-root='.length); | 68 packageRoot = new Path(arg.substring('--package-root='.length)); |
| 71 } else if (arg.startsWith('--version=')) { | 69 } else if (arg.startsWith('--version=')) { |
| 72 version = arg.substring('--version='.length); | 70 version = arg.substring('--version='.length); |
| 73 } else { | 71 } else { |
| 74 print('Unknown option: $arg'); | 72 print('Unknown option: $arg'); |
| 75 return; | 73 return; |
| 76 } | 74 } |
| 77 break; | 75 break; |
| 78 } | 76 } |
| 79 } | 77 } |
| 80 | 78 |
| (...skipping 18 matching lines...) Expand all Loading... |
| 99 | 97 |
| 100 print('Cross-referencing dart:html...'); | 98 print('Cross-referencing dart:html...'); |
| 101 // TODO(amouravski): move HtmlDiff inside of the future chain below to re-use | 99 // TODO(amouravski): move HtmlDiff inside of the future chain below to re-use |
| 102 // the MirrorSystem already analyzed. | 100 // the MirrorSystem already analyzed. |
| 103 _diff = new HtmlDiff(printWarnings:false); | 101 _diff = new HtmlDiff(printWarnings:false); |
| 104 Future htmlDiff = _diff.run(libPath); | 102 Future htmlDiff = _diff.run(libPath); |
| 105 | 103 |
| 106 // TODO(johnniwinther): Libraries for the compilation seem to be more like | 104 // TODO(johnniwinther): Libraries for the compilation seem to be more like |
| 107 // URIs. Perhaps Path should have a toURI() method. | 105 // URIs. Perhaps Path should have a toURI() method. |
| 108 // Add all of the core libraries. | 106 // Add all of the core libraries. |
| 109 final apidocLibraries = <Uri>[]; | 107 final apidocLibraries = <Path>[]; |
| 110 LIBRARIES.forEach((String name, LibraryInfo info) { | 108 LIBRARIES.forEach((String name, LibraryInfo info) { |
| 111 if (info.documented) { | 109 if (info.documented) { |
| 112 apidocLibraries.add(Uri.parse('dart:$name')); | 110 apidocLibraries.add(new Path('dart:$name')); |
| 113 } | 111 } |
| 114 }); | 112 }); |
| 115 | 113 |
| 116 // TODO(amouravski): This code is really wonky. | 114 // TODO(amouravski): This code is really wonky. |
| 117 var lister = new Directory.fromPath(scriptDir.append('../../pkg')).list(); | 115 var lister = new Directory.fromPath(scriptDir.append('../../pkg')).list(); |
| 118 lister.listen((entity) { | 116 lister.listen((entity) { |
| 119 if (entity is Directory) { | 117 if (entity is Directory) { |
| 120 var path = new Path(entity.path); | 118 var path = new Path(entity.path); |
| 121 var libName = path.filename; | 119 var libName = path.filename; |
| 122 var libPath = path.append('lib/$libName.dart'); | 120 var libPath = path.append('lib/$libName.dart'); |
| 123 | 121 |
| 124 // Ignore some libraries. | 122 // Ignore some libraries. |
| 125 if (excludedLibraries.contains(libName)) { | 123 if (excludedLibraries.contains(libName)) { |
| 126 return; | 124 return; |
| 127 } | 125 } |
| 128 | 126 |
| 129 // Ignore hidden directories (like .svn) as well as pkg.xcodeproj. | 127 // Ignore hidden directories (like .svn) as well as pkg.xcodeproj. |
| 130 if (libName.startsWith('.') || libName.endsWith('.xcodeproj')) { | 128 if (libName.startsWith('.') || libName.endsWith('.xcodeproj')) { |
| 131 return; | 129 return; |
| 132 } | 130 } |
| 133 | 131 |
| 134 if (new File.fromPath(libPath).existsSync()) { | 132 if (new File.fromPath(libPath).existsSync()) { |
| 135 apidocLibraries.add(_pathToFileUri(libPath.toNativePath())); | 133 apidocLibraries.add(libPath); |
| 136 includedLibraries.add(libName); | 134 includedLibraries.add(libName); |
| 137 } else { | 135 } else { |
| 138 print('Warning: could not find package at $path'); | 136 print('Warning: could not find package at $path'); |
| 139 } | 137 } |
| 140 } | 138 } |
| 141 }, onDone: () { | 139 }, onDone: () { |
| 142 final apidoc = new Apidoc(mdn, outputDir, mode, generateAppCache, | 140 final apidoc = new Apidoc(mdn, outputDir, mode, generateAppCache, |
| 143 excludedLibraries, version); | 141 excludedLibraries, version); |
| 144 apidoc.dartdocPath = | 142 apidoc.dartdocPath = |
| 145 scriptDir.append('../../sdk/lib/_internal/dartdoc/'); | 143 scriptDir.append('../../sdk/lib/_internal/dartdoc/'); |
| 146 // Select the libraries to include in the produced documentation: | 144 // Select the libraries to include in the produced documentation: |
| 147 apidoc.includeApi = true; | 145 apidoc.includeApi = true; |
| 148 apidoc.includedLibraries = includedLibraries; | 146 apidoc.includedLibraries = includedLibraries; |
| 149 | 147 |
| 150 // TODO(amouravski): make apidoc use roughly the same flow as bin/dartdoc. | 148 // TODO(amouravski): make apidoc use roughly the same flow as bin/dartdoc. |
| 151 Future.wait([copiedStatic, copiedApiDocStatic, htmlDiff]) | 149 Future.wait([copiedStatic, copiedApiDocStatic, htmlDiff]) |
| 152 .then((_) => apidoc.documentLibraries(apidocLibraries, libPath, | 150 .then((_) => apidoc.documentLibraries( apidocLibraries, libPath, |
| 153 packageRoot)) | 151 packageRoot)) |
| 154 .then((_) => compileScript(mode, outputDir, libPath)) | 152 .then((_) => compileScript(mode, outputDir, libPath)) |
| 155 .then((_) => print(apidoc.status)) | 153 .then((_) => print(apidoc.status)) |
| 156 .catchError((e) { | 154 .catchError((e) { |
| 157 print('Error: generation failed: ${e}'); | 155 print('Error: generation failed: ${e}'); |
| 158 apidoc.cleanup(); | 156 apidoc.cleanup(); |
| 159 exit(1); | 157 exit(1); |
| 160 }) | 158 }) |
| 161 .whenComplete(() => apidoc.cleanup()); | 159 .whenComplete(() => apidoc.cleanup()); |
| 162 }); | 160 }); |
| (...skipping 279 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 442 final typeName = member.owner.simpleName; | 440 final typeName = member.owner.simpleName; |
| 443 var memberName = '$typeName.${member.simpleName}'; | 441 var memberName = '$typeName.${member.simpleName}'; |
| 444 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { | 442 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { |
| 445 final separator = member.constructorName == '' ? '' : '.'; | 443 final separator = member.constructorName == '' ? '' : '.'; |
| 446 memberName = 'new $typeName$separator${member.constructorName}'; | 444 memberName = 'new $typeName$separator${member.constructorName}'; |
| 447 } | 445 } |
| 448 | 446 |
| 449 return a(memberUrl(member), memberName); | 447 return a(memberUrl(member), memberName); |
| 450 } | 448 } |
| 451 } | 449 } |
| 452 | |
| 453 /** Converts a local path string to a `file:` [Uri]. */ | |
| 454 Uri _pathToFileUri(String path) { | |
| 455 path = pathos.absolute(path); | |
| 456 if (Platform.operatingSystem != 'windows') { | |
| 457 return Uri.parse('file://$path'); | |
| 458 } else { | |
| 459 return Uri.parse('file:///${path.replaceAll("\\", "/")}'); | |
| 460 } | |
| 461 } | |
| 462 | |
| OLD | NEW |