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 * To generate docs for a library, run this script with the path to an | 6 * To generate docs for a library, run this script with the path to an |
7 * entrypoint .dart file, like: | 7 * entrypoint .dart file, like: |
8 * | 8 * |
9 * $ dart dartdoc.dart foo.dart | 9 * $ dart dartdoc.dart foo.dart |
10 * | 10 * |
11 * This will create a "docs" directory with the docs for your libraries. To | 11 * This will create a "docs" directory with the docs for your libraries. To |
12 * create these beautiful docs, dartdoc parses your library and every library | 12 * create these beautiful docs, dartdoc parses your library and every library |
13 * it imports (recursively). From each library, it parses all classes and | 13 * it imports (recursively). From each library, it parses all classes and |
14 * members, finds the associated doc comments and builds crosslinked docs from | 14 * members, finds the associated doc comments and builds crosslinked docs from |
15 * them. | 15 * them. |
16 */ | 16 */ |
17 #library('dartdoc'); | 17 #library('dartdoc'); |
18 | 18 |
19 #import('dart:io'); | 19 #import('dart:io'); |
20 #import('dart:math'); | 20 #import('dart:math'); |
21 #import('dart:uri'); | 21 #import('dart:uri'); |
22 #import('dart:json'); | 22 #import('dart:json'); |
23 #import('mirrors/mirrors.dart'); | 23 #import('mirrors/mirrors.dart'); |
24 #import('mirrors/mirrors_util.dart'); | 24 #import('mirrors/mirrors_util.dart'); |
25 #import('mirrors/dart2js_mirror.dart', prefix: 'dart2js'); | 25 #import('mirrors/dart2js_mirror.dart', prefix: 'dart2js'); |
26 #import('classify.dart'); | 26 #import('classify.dart'); |
27 #import('markdown.dart', prefix: 'md'); | 27 #import('markdown.dart', prefix: 'md'); |
28 #import('../../lib/compiler/implementation/scanner/scannerlib.dart', | 28 #import('../../lib/compiler/implementation/scanner/scannerlib.dart', |
29 prefix: 'dart2js'); | 29 prefix: 'dart2js'); |
30 #import('../../lib/compiler/implementation/library_map.dart'); | 30 #import('../../lib/_internal/libraries.dart'); |
31 | 31 |
32 #source('comment_map.dart'); | 32 #source('comment_map.dart'); |
33 #source('utils.dart'); | 33 #source('utils.dart'); |
34 | 34 |
35 // TODO(johnniwinther): Note that [IN_SDK] gets initialized to true when this | 35 // TODO(johnniwinther): Note that [IN_SDK] gets initialized to true when this |
36 // file is modified by the SDK deployment script. If you change, be sure to test | 36 // file is modified by the SDK deployment script. If you change, be sure to test |
37 // that dartdoc still works when run from the built SDK directory. | 37 // that dartdoc still works when run from the built SDK directory. |
38 final bool IN_SDK = false; | 38 final bool IN_SDK = false; |
39 | 39 |
40 /** | 40 /** |
(...skipping 339 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
380 /** The path to the file currently being written to, relative to [outdir]. */ | 380 /** The path to the file currently being written to, relative to [outdir]. */ |
381 Path _filePath; | 381 Path _filePath; |
382 | 382 |
383 /** The file currently being written to. */ | 383 /** The file currently being written to. */ |
384 StringBuffer _file; | 384 StringBuffer _file; |
385 | 385 |
386 int _totalLibraries = 0; | 386 int _totalLibraries = 0; |
387 int _totalTypes = 0; | 387 int _totalTypes = 0; |
388 int _totalMembers = 0; | 388 int _totalMembers = 0; |
389 | 389 |
390 Dartdoc() | 390 Dartdoc() : _comments = new CommentMap() { |
391 : _comments = new CommentMap() { | |
392 // Patch in support for [:...:]-style code to the markdown parser. | 391 // Patch in support for [:...:]-style code to the markdown parser. |
393 // TODO(rnystrom): Markdown already has syntax for this. Phase this out? | 392 // TODO(rnystrom): Markdown already has syntax for this. Phase this out? |
394 md.InlineParser.syntaxes.insertRange(0, 1, | 393 md.InlineParser.syntaxes.insertRange(0, 1, |
395 new md.CodeSyntax(@'\[\:((?:.|\n)*?)\:\]')); | 394 new md.CodeSyntax(@'\[\:((?:.|\n)*?)\:\]')); |
396 | 395 |
397 md.setImplicitLinkResolver((name) => resolveNameReference(name, | 396 md.setImplicitLinkResolver((name) => resolveNameReference(name, |
398 currentLibrary: _currentLibrary, currentType: _currentType, | 397 currentLibrary: _currentLibrary, currentType: _currentType, |
399 currentMember: _currentMember)); | 398 currentMember: _currentMember)); |
400 } | 399 } |
401 | 400 |
(...skipping 10 matching lines...) Expand all Loading... |
412 includeByDefault = false; | 411 includeByDefault = false; |
413 if (includedLibraries.indexOf(libraryName) != -1) { | 412 if (includedLibraries.indexOf(libraryName) != -1) { |
414 return true; | 413 return true; |
415 } | 414 } |
416 } | 415 } |
417 if (excludedLibraries.indexOf(libraryName) != -1) { | 416 if (excludedLibraries.indexOf(libraryName) != -1) { |
418 return false; | 417 return false; |
419 } | 418 } |
420 if (libraryName.startsWith('dart:')) { | 419 if (libraryName.startsWith('dart:')) { |
421 String suffix = libraryName.substring('dart:'.length); | 420 String suffix = libraryName.substring('dart:'.length); |
422 LibraryInfo info = DART2JS_LIBRARY_MAP[suffix]; | 421 LibraryInfo info = LIBRARIES[suffix]; |
423 if (info != null) { | 422 if (info != null) { |
424 return !info.isInternal && includeApi; | 423 return info.documented && includeApi; |
425 } | 424 } |
426 } | 425 } |
427 return includeByDefault; | 426 return includeByDefault; |
428 } | 427 } |
429 | 428 |
430 /** | 429 /** |
431 * Returns `true` if links to the public API should be generated for | 430 * Returns `true` if links to the public API should be generated for |
432 * [library]. | 431 * [library]. |
433 */ | 432 */ |
434 bool shouldLinkToPublicApi(LibraryMirror library) { | 433 bool shouldLinkToPublicApi(LibraryMirror library) { |
435 if (linkToApi) { | 434 if (linkToApi) { |
436 String libraryName = library.simpleName; | 435 String libraryName = library.simpleName; |
437 if (libraryName.startsWith('dart:')) { | 436 if (libraryName.startsWith('dart:')) { |
438 String suffix = libraryName.substring('dart:'.length); | 437 String suffix = libraryName.substring('dart:'.length); |
439 LibraryInfo info = DART2JS_LIBRARY_MAP[suffix]; | 438 LibraryInfo info = LIBRARIES[suffix]; |
440 if (info != null) { | 439 if (info != null) { |
441 return !info.isInternal; | 440 return info.documented; |
442 } | 441 } |
443 } | 442 } |
444 } | 443 } |
445 return false; | 444 return false; |
446 } | 445 } |
447 | 446 |
448 String get footerContent(){ | 447 String get footerContent(){ |
449 var footerItems = []; | 448 var footerItems = []; |
450 if(!omitGenerationTime) { | 449 if (!omitGenerationTime) { |
451 footerItems.add("This page was generated at ${new Date.now()}"); | 450 footerItems.add("This page was generated at ${new Date.now()}"); |
452 } | 451 } |
453 if(footerText != null) { | 452 if (footerText != null) { |
454 footerItems.add(footerText); | 453 footerItems.add(footerText); |
455 } | 454 } |
456 var content = ''; | 455 var content = ''; |
457 for (int i = 0; i < footerItems.length; i++) { | 456 for (int i = 0; i < footerItems.length; i++) { |
458 if(i > 0){ | 457 if (i > 0) { |
459 content = content.concat('\n'); | 458 content = content.concat('\n'); |
460 } | 459 } |
461 content = content.concat('<div>${footerItems[i]}</div>'); | 460 content = content.concat('<div>${footerItems[i]}</div>'); |
462 } | 461 } |
463 return content; | 462 return content; |
464 } | 463 } |
465 | 464 |
466 void documentEntryPoint(Path entrypoint, Path libPath) { | 465 void documentEntryPoint(Path entrypoint, Path libPath) { |
467 final compilation = new Compilation(entrypoint, libPath); | 466 final compilation = new Compilation(entrypoint, libPath); |
468 _document(compilation); | 467 _document(compilation); |
(...skipping 1120 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1589 } | 1588 } |
1590 | 1589 |
1591 /** | 1590 /** |
1592 * Returns [:true:] if [type] should be regarded as an exception. | 1591 * Returns [:true:] if [type] should be regarded as an exception. |
1593 */ | 1592 */ |
1594 bool isException(TypeMirror type) { | 1593 bool isException(TypeMirror type) { |
1595 return type.simpleName.endsWith('Exception'); | 1594 return type.simpleName.endsWith('Exception'); |
1596 } | 1595 } |
1597 } | 1596 } |
1598 | 1597 |
OLD | NEW |