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('nav.dart'); | 33 #source('nav.dart'); |
34 #source('utils.dart'); | 34 #source('utils.dart'); |
35 | 35 |
36 // TODO(johnniwinther): Note that [IN_SDK] gets initialized to true when this | 36 // TODO(johnniwinther): Note that [IN_SDK] gets initialized to true when this |
37 // file is modified by the SDK deployment script. If you change, be sure to test | 37 // file is modified by the SDK deployment script. If you change, be sure to test |
38 // that dartdoc still works when run from the built SDK directory. | 38 // that dartdoc still works when run from the built SDK directory. |
39 final bool IN_SDK = false; | 39 final bool IN_SDK = false; |
40 | 40 |
(...skipping 347 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
388 /** The file currently being written to. */ | 388 /** The file currently being written to. */ |
389 StringBuffer _file; | 389 StringBuffer _file; |
390 | 390 |
391 int _totalLibraries = 0; | 391 int _totalLibraries = 0; |
392 int _totalTypes = 0; | 392 int _totalTypes = 0; |
393 int _totalMembers = 0; | 393 int _totalMembers = 0; |
394 | 394 |
395 Dartdoc() | 395 Dartdoc() |
396 : _comments = new CommentMap(), | 396 : _comments = new CommentMap(), |
397 dartdocPath = scriptDir { | 397 dartdocPath = scriptDir { |
398 | |
399 // Patch in support for [:...:]-style code to the markdown parser. | 398 // Patch in support for [:...:]-style code to the markdown parser. |
400 // TODO(rnystrom): Markdown already has syntax for this. Phase this out? | 399 // TODO(rnystrom): Markdown already has syntax for this. Phase this out? |
401 md.InlineParser.syntaxes.insertRange(0, 1, | 400 md.InlineParser.syntaxes.insertRange(0, 1, |
402 new md.CodeSyntax(@'\[\:((?:.|\n)*?)\:\]')); | 401 new md.CodeSyntax(@'\[\:((?:.|\n)*?)\:\]')); |
403 | 402 |
404 md.setImplicitLinkResolver((name) => resolveNameReference(name, | 403 md.setImplicitLinkResolver((name) => resolveNameReference(name, |
405 currentLibrary: _currentLibrary, currentType: _currentType, | 404 currentLibrary: _currentLibrary, currentType: _currentType, |
406 currentMember: _currentMember)); | 405 currentMember: _currentMember)); |
407 } | 406 } |
408 | 407 |
(...skipping 10 matching lines...) Expand all Loading... |
419 includeByDefault = false; | 418 includeByDefault = false; |
420 if (includedLibraries.indexOf(libraryName) != -1) { | 419 if (includedLibraries.indexOf(libraryName) != -1) { |
421 return true; | 420 return true; |
422 } | 421 } |
423 } | 422 } |
424 if (excludedLibraries.indexOf(libraryName) != -1) { | 423 if (excludedLibraries.indexOf(libraryName) != -1) { |
425 return false; | 424 return false; |
426 } | 425 } |
427 if (libraryName.startsWith('dart:')) { | 426 if (libraryName.startsWith('dart:')) { |
428 String suffix = libraryName.substring('dart:'.length); | 427 String suffix = libraryName.substring('dart:'.length); |
429 LibraryInfo info = DART2JS_LIBRARY_MAP[suffix]; | 428 LibraryInfo info = LIBRARIES[suffix]; |
430 if (info != null) { | 429 if (info != null) { |
431 return !info.isInternal && includeApi; | 430 return info.documented && includeApi; |
432 } | 431 } |
433 } | 432 } |
434 return includeByDefault; | 433 return includeByDefault; |
435 } | 434 } |
436 | 435 |
437 /** | 436 /** |
438 * Returns `true` if links to the public API should be generated for | 437 * Returns `true` if links to the public API should be generated for |
439 * [library]. | 438 * [library]. |
440 */ | 439 */ |
441 bool shouldLinkToPublicApi(LibraryMirror library) { | 440 bool shouldLinkToPublicApi(LibraryMirror library) { |
442 if (linkToApi) { | 441 if (linkToApi) { |
443 String libraryName = library.simpleName; | 442 String libraryName = library.simpleName; |
444 if (libraryName.startsWith('dart:')) { | 443 if (libraryName.startsWith('dart:')) { |
445 String suffix = libraryName.substring('dart:'.length); | 444 String suffix = libraryName.substring('dart:'.length); |
446 LibraryInfo info = DART2JS_LIBRARY_MAP[suffix]; | 445 LibraryInfo info = LIBRARIES[suffix]; |
447 if (info != null) { | 446 if (info != null) { |
448 return !info.isInternal; | 447 return info.documented; |
449 } | 448 } |
450 } | 449 } |
451 } | 450 } |
452 return false; | 451 return false; |
453 } | 452 } |
454 | 453 |
455 String get footerContent(){ | 454 String get footerContent(){ |
456 var footerItems = []; | 455 var footerItems = []; |
457 if(!omitGenerationTime) { | 456 if (!omitGenerationTime) { |
458 footerItems.add("This page was generated at ${new Date.now()}"); | 457 footerItems.add("This page was generated at ${new Date.now()}"); |
459 } | 458 } |
460 if(footerText != null) { | 459 if (footerText != null) { |
461 footerItems.add(footerText); | 460 footerItems.add(footerText); |
462 } | 461 } |
463 var content = ''; | 462 var content = ''; |
464 for (int i = 0; i < footerItems.length; i++) { | 463 for (int i = 0; i < footerItems.length; i++) { |
465 if(i > 0){ | 464 if (i > 0) { |
466 content = content.concat('\n'); | 465 content = content.concat('\n'); |
467 } | 466 } |
468 content = content.concat('<div>${footerItems[i]}</div>'); | 467 content = content.concat('<div>${footerItems[i]}</div>'); |
469 } | 468 } |
470 return content; | 469 return content; |
471 } | 470 } |
472 | 471 |
473 void documentEntryPoint(Path entrypoint, Path libPath) { | 472 void documentEntryPoint(Path entrypoint, Path libPath) { |
474 final compilation = new Compilation(entrypoint, libPath); | 473 final compilation = new Compilation(entrypoint, libPath); |
475 _document(compilation); | 474 _document(compilation); |
(...skipping 1245 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1721 } | 1720 } |
1722 | 1721 |
1723 /** | 1722 /** |
1724 * Returns [:true:] if [type] should be regarded as an exception. | 1723 * Returns [:true:] if [type] should be regarded as an exception. |
1725 */ | 1724 */ |
1726 bool isException(TypeMirror type) { | 1725 bool isException(TypeMirror type) { |
1727 return type.simpleName.endsWith('Exception'); | 1726 return type.simpleName.endsWith('Exception'); |
1728 } | 1727 } |
1729 } | 1728 } |
1730 | 1729 |
OLD | NEW |