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 17 matching lines...) Expand all Loading... |
28 | 28 |
29 void main() { | 29 void main() { |
30 final args = new Options().arguments; | 30 final args = new Options().arguments; |
31 | 31 |
32 int mode = doc.MODE_STATIC; | 32 int mode = doc.MODE_STATIC; |
33 Path outputDir = new Path('docs'); | 33 Path outputDir = new Path('docs'); |
34 bool generateAppCache = false; | 34 bool generateAppCache = false; |
35 | 35 |
36 List<String> excludedLibraries = <String>[]; | 36 List<String> excludedLibraries = <String>[]; |
37 List<String> includedLibraries = <String>[]; | 37 List<String> includedLibraries = <String>[]; |
38 var pkgPath; | 38 Path pkgPath; |
39 String version; | 39 String version; |
40 | 40 |
41 // Parse the command-line arguments. | 41 // Parse the command-line arguments. |
42 for (int i = 0; i < args.length; i++) { | 42 for (int i = 0; i < args.length; i++) { |
43 final arg = args[i]; | 43 final arg = args[i]; |
44 | 44 |
45 switch (arg) { | 45 switch (arg) { |
46 case '--mode=static': | 46 case '--mode=static': |
47 mode = doc.MODE_STATIC; | 47 mode = doc.MODE_STATIC; |
48 break; | 48 break; |
49 | 49 |
50 case '--mode=live-nav': | 50 case '--mode=live-nav': |
51 mode = doc.MODE_LIVE_NAV; | 51 mode = doc.MODE_LIVE_NAV; |
52 break; | 52 break; |
53 | 53 |
54 case '--generate-app-cache=true': | 54 case '--generate-app-cache=true': |
55 generateAppCache = true; | 55 generateAppCache = true; |
56 break; | 56 break; |
57 | 57 |
58 default: | 58 default: |
59 if (arg.startsWith('--exclude-lib=')) { | 59 if (arg.startsWith('--exclude-lib=')) { |
60 excludedLibraries.add(arg.substring('--exclude-lib='.length)); | 60 excludedLibraries.add(arg.substring('--exclude-lib='.length)); |
61 } else if (arg.startsWith('--include-lib=')) { | 61 } else if (arg.startsWith('--include-lib=')) { |
62 includedLibraries.add(arg.substring('--include-lib='.length)); | 62 includedLibraries.add(arg.substring('--include-lib='.length)); |
63 } else if (arg.startsWith('--out=')) { | 63 } else if (arg.startsWith('--out=')) { |
64 outputDir = new Path(arg.substring('--out='.length)); | 64 outputDir = new Path(arg.substring('--out='.length)); |
65 } else if (arg.startsWith('--pkg=')) { | 65 } else if (arg.startsWith('--pkg=')) { |
66 pkgPath = arg.substring('--pkg='.length); | 66 pkgPath = new Path(arg.substring('--pkg='.length)); |
67 } else if (arg.startsWith('--version=')) { | 67 } else if (arg.startsWith('--version=')) { |
68 version = arg.substring('--version='.length); | 68 version = arg.substring('--version='.length); |
69 } else { | 69 } else { |
70 print('Unknown option: $arg'); | 70 print('Unknown option: $arg'); |
71 return; | 71 return; |
72 } | 72 } |
73 break; | 73 break; |
74 } | 74 } |
75 } | 75 } |
76 | 76 |
77 final libPath = doc.scriptDir.append('../../sdk/'); | 77 final libPath = doc.scriptDir.append('../../sdk/'); |
78 | 78 |
79 doc.cleanOutputDirectory(outputDir); | 79 doc.cleanOutputDirectory(outputDir); |
80 | 80 |
81 // The basic dartdoc-provided static content. | 81 // The basic dartdoc-provided static content. |
82 final copiedStatic = doc.copyDirectory( | 82 final copiedStatic = doc.copyDirectory( |
83 doc.scriptDir.append('../../sdk/lib/_internal/dartdoc/static'), | 83 doc.scriptDir.append('../../sdk/lib/_internal/dartdoc/static'), |
84 outputDir); | 84 outputDir); |
85 | 85 |
86 // The apidoc-specific static content. | 86 // The apidoc-specific static content. |
87 final copiedApiDocStatic = doc.copyDirectory( | 87 final copiedApiDocStatic = doc.copyDirectory( |
88 doc.scriptDir.append('static'), | 88 doc.scriptDir.append('static'), |
89 outputDir); | 89 outputDir); |
90 | 90 |
91 print('Parsing MDN data...'); | 91 print('Parsing MDN data...'); |
92 final mdnFile = new File.fromPath(doc.scriptDir.append('mdn/database.json')); | 92 final mdnFile = new File.fromPath(doc.scriptDir.append('mdn/database.json')); |
93 final mdn = json.parse(mdnFile.readAsStringSync()); | 93 final mdn = json.parse(mdnFile.readAsStringSync()); |
94 | 94 |
95 print('Cross-referencing dart:html...'); | 95 print('Cross-referencing dart:html...'); |
96 HtmlDiff.initialize(libPath); | |
97 _diff = new HtmlDiff(printWarnings:false); | 96 _diff = new HtmlDiff(printWarnings:false); |
98 _diff.run(); | 97 Future htmlDiff = _diff.run(libPath); |
99 | 98 |
100 // Process libraries. | 99 // Process libraries. |
101 | 100 |
102 // TODO(johnniwinther): Libraries for the compilation seem to be more like | 101 // TODO(johnniwinther): Libraries for the compilation seem to be more like |
103 // URIs. Perhaps Path should have a toURI() method. | 102 // URIs. Perhaps Path should have a toURI() method. |
104 // Add all of the core libraries. | 103 // Add all of the core libraries. |
105 final apidocLibraries = <Path>[]; | 104 final apidocLibraries = <Path>[]; |
106 LIBRARIES.forEach((String name, LibraryInfo info) { | 105 LIBRARIES.forEach((String name, LibraryInfo info) { |
107 if (info.documented) { | 106 if (info.documented) { |
108 apidocLibraries.add(new Path('dart:$name')); | 107 apidocLibraries.add(new Path('dart:$name')); |
(...skipping 31 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
140 onDone: () { | 139 onDone: () { |
141 print('Generating docs...'); | 140 print('Generating docs...'); |
142 final apidoc = new Apidoc(mdn, outputDir, mode, generateAppCache, | 141 final apidoc = new Apidoc(mdn, outputDir, mode, generateAppCache, |
143 excludedLibraries, version); | 142 excludedLibraries, version); |
144 apidoc.dartdocPath = | 143 apidoc.dartdocPath = |
145 doc.scriptDir.append('../../sdk/lib/_internal/dartdoc/'); | 144 doc.scriptDir.append('../../sdk/lib/_internal/dartdoc/'); |
146 // Select the libraries to include in the produced documentation: | 145 // Select the libraries to include in the produced documentation: |
147 apidoc.includeApi = true; | 146 apidoc.includeApi = true; |
148 apidoc.includedLibraries = includedLibraries; | 147 apidoc.includedLibraries = includedLibraries; |
149 | 148 |
150 Future.wait([copiedStatic, copiedApiDocStatic]).then((_) { | 149 Future.wait([copiedStatic, copiedApiDocStatic, htmlDiff]).then((_) { |
151 apidoc.documentLibraries(apidocLibraries, libPath, pkgPath); | 150 Future<bool> documented = |
| 151 apidoc.documentLibraries(apidocLibraries, libPath, pkgPath); |
152 | 152 |
153 final compiled = doc.compileScript(mode, outputDir, libPath); | 153 documented.then((_) { |
| 154 final compiled = doc.compileScript(mode, outputDir, libPath); |
154 | 155 |
155 Future.wait([compiled, copiedStatic, copiedApiDocStatic]).then((_) { | 156 Future.wait([compiled]).then((_) { |
| 157 apidoc.cleanup(); |
| 158 }); |
| 159 }, onError: (AsyncError asyncError) { |
| 160 print('Generation failed: ${asyncError.error}'); |
156 apidoc.cleanup(); | 161 apidoc.cleanup(); |
157 }); | 162 }); |
158 }); | 163 }); |
159 }); | 164 }); |
160 } | 165 } |
161 | 166 |
162 class Apidoc extends doc.Dartdoc { | 167 class Apidoc extends doc.Dartdoc { |
163 /** Big ball of JSON containing the scraped MDN documentation. */ | 168 /** Big ball of JSON containing the scraped MDN documentation. */ |
164 final Map mdn; | 169 final Map mdn; |
165 | 170 |
(...skipping 155 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
321 <a href="$CCA">Creative Commons: Attribution-Sharealike license</a>. | 326 <a href="$CCA">Creative Commons: Attribution-Sharealike license</a>. |
322 Mozilla has no other association with Dart or dartlang.org. We | 327 Mozilla has no other association with Dart or dartlang.org. We |
323 encourage you to improve the web by | 328 encourage you to improve the web by |
324 <a href="$CONTRIB">contributing</a> to | 329 <a href="$CONTRIB">contributing</a> to |
325 <a href="$MDN">The Mozilla Developer Network</a>. | 330 <a href="$MDN">The Mozilla Developer Network</a>. |
326 </p> | 331 </p> |
327 '''); | 332 '''); |
328 } | 333 } |
329 } | 334 } |
330 | 335 |
331 doc.MdnComment lookupMdnComment(Mirror mirror) { | 336 doc.MdnComment lookupMdnComment(Mirror mirror) { |
332 if (mirror is TypeMirror) { | 337 if (mirror is TypeMirror) { |
333 return includeMdnTypeComment(mirror); | 338 return includeMdnTypeComment(mirror); |
334 } else if (mirror is MemberMirror) { | 339 } else if (mirror is MemberMirror) { |
335 return includeMdnMemberComment(mirror); | 340 return includeMdnMemberComment(mirror); |
336 } else { | 341 } else { |
337 return null; | 342 return null; |
338 } | 343 } |
339 } | 344 } |
340 | 345 |
341 /** | 346 /** |
(...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
376 if (mdnType['summary'].trim().isEmpty) return null; | 381 if (mdnType['summary'].trim().isEmpty) return null; |
377 | 382 |
378 // Remember which MDN page we're using so we can attribute it. | 383 // Remember which MDN page we're using so we can attribute it. |
379 return new doc.MdnComment(mdnType['summary'], mdnType['srcUrl']); | 384 return new doc.MdnComment(mdnType['summary'], mdnType['srcUrl']); |
380 } | 385 } |
381 | 386 |
382 /** | 387 /** |
383 * Gets the MDN-scraped docs for [member], or `null` if this type isn't | 388 * Gets the MDN-scraped docs for [member], or `null` if this type isn't |
384 * scraped from MDN. | 389 * scraped from MDN. |
385 */ | 390 */ |
386 MdnComment includeMdnMemberComment(MemberMirror member) { | 391 doc.MdnComment includeMdnMemberComment(MemberMirror member) { |
387 var library = findLibrary(member); | 392 var library = findLibrary(member); |
388 var memberString = ''; | 393 var memberString = ''; |
389 if (HTML_LIBRARY_NAMES.contains(doc.displayName(library))) { | 394 if (HTML_LIBRARY_NAMES.contains(doc.displayName(library))) { |
390 // If it's an HTML type, try to map it to a DOM type name so we can find | 395 // If it's an HTML type, try to map it to a DOM type name so we can find |
391 // the MDN docs. | 396 // the MDN docs. |
392 final domMembers = _diff.htmlToDom[member.qualifiedName]; | 397 final domMembers = _diff.htmlToDom[member.qualifiedName]; |
393 | 398 |
394 // Couldn't find a DOM type. | 399 // Couldn't find a DOM type. |
395 if ((domMembers == null) || (domMembers.length != 1)) return null; | 400 if ((domMembers == null) || (domMembers.length != 1)) return null; |
396 | 401 |
(...skipping 43 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
440 final typeName = member.owner.simpleName; | 445 final typeName = member.owner.simpleName; |
441 var memberName = '$typeName.${member.simpleName}'; | 446 var memberName = '$typeName.${member.simpleName}'; |
442 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { | 447 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { |
443 final separator = member.constructorName == '' ? '' : '.'; | 448 final separator = member.constructorName == '' ? '' : '.'; |
444 memberName = 'new $typeName$separator${member.constructorName}'; | 449 memberName = 'new $typeName$separator${member.constructorName}'; |
445 } | 450 } |
446 | 451 |
447 return a(memberUrl(member), memberName); | 452 return a(memberUrl(member), memberName); |
448 } | 453 } |
449 } | 454 } |
OLD | NEW |