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 * |
(...skipping 240 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
251 | 251 |
252 /** | 252 /** |
253 * Returns `true` if [library] is included in the generated documentation. | 253 * Returns `true` if [library] is included in the generated documentation. |
254 */ | 254 */ |
255 bool shouldIncludeLibrary(LibraryMirror library) { | 255 bool shouldIncludeLibrary(LibraryMirror library) { |
256 if (shouldLinkToPublicApi(library)) { | 256 if (shouldLinkToPublicApi(library)) { |
257 return false; | 257 return false; |
258 } | 258 } |
259 var includeByDefault = true; | 259 var includeByDefault = true; |
260 String libraryName = library.simpleName; | 260 String libraryName = library.simpleName; |
261 if (!includedLibraries.isEmpty()) { | 261 if (!includedLibraries.isEmpty) { |
262 includeByDefault = false; | 262 includeByDefault = false; |
263 if (includedLibraries.indexOf(libraryName) != -1) { | 263 if (includedLibraries.indexOf(libraryName) != -1) { |
264 return true; | 264 return true; |
265 } | 265 } |
266 } | 266 } |
267 if (excludedLibraries.indexOf(libraryName) != -1) { | 267 if (excludedLibraries.indexOf(libraryName) != -1) { |
268 return false; | 268 return false; |
269 } | 269 } |
270 if (libraryName.startsWith('dart:')) { | 270 if (libraryName.startsWith('dart:')) { |
271 String suffix = libraryName.substring('dart:'.length); | 271 String suffix = libraryName.substring('dart:'.length); |
(...skipping 293 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
565 for (final library in _sortedLibraries) { | 565 for (final library in _sortedLibraries) { |
566 docLibraryNavigationJson(library, libraryList); | 566 docLibraryNavigationJson(library, libraryList); |
567 } | 567 } |
568 return libraryList; | 568 return libraryList; |
569 } | 569 } |
570 | 570 |
571 void docLibraryNavigationJson(LibraryMirror library, List libraryList) { | 571 void docLibraryNavigationJson(LibraryMirror library, List libraryList) { |
572 var libraryInfo = {}; | 572 var libraryInfo = {}; |
573 libraryInfo[NAME] = library.simpleName; | 573 libraryInfo[NAME] = library.simpleName; |
574 final List members = docMembersJson(library.declaredMembers); | 574 final List members = docMembersJson(library.declaredMembers); |
575 if (!members.isEmpty()) { | 575 if (!members.isEmpty) { |
576 libraryInfo[MEMBERS] = members; | 576 libraryInfo[MEMBERS] = members; |
577 } | 577 } |
578 | 578 |
579 final types = []; | 579 final types = []; |
580 for (InterfaceMirror type in orderByName(library.types.getValues())) { | 580 for (InterfaceMirror type in orderByName(library.types.getValues())) { |
581 if (!showPrivate && type.isPrivate) continue; | 581 if (!showPrivate && type.isPrivate) continue; |
582 | 582 |
583 var typeInfo = {}; | 583 var typeInfo = {}; |
584 typeInfo[NAME] = type.displayName; | 584 typeInfo[NAME] = type.displayName; |
585 if (type.isClass) { | 585 if (type.isClass) { |
586 typeInfo[KIND] = CLASS; | 586 typeInfo[KIND] = CLASS; |
587 } else if (type.isInterface) { | 587 } else if (type.isInterface) { |
588 typeInfo[KIND] = INTERFACE; | 588 typeInfo[KIND] = INTERFACE; |
589 } else { | 589 } else { |
590 assert(type.isTypedef); | 590 assert(type.isTypedef); |
591 typeInfo[KIND] = TYPEDEF; | 591 typeInfo[KIND] = TYPEDEF; |
592 } | 592 } |
593 final List typeMembers = docMembersJson(type.declaredMembers); | 593 final List typeMembers = docMembersJson(type.declaredMembers); |
594 if (!typeMembers.isEmpty()) { | 594 if (!typeMembers.isEmpty) { |
595 typeInfo[MEMBERS] = typeMembers; | 595 typeInfo[MEMBERS] = typeMembers; |
596 } | 596 } |
597 | 597 |
598 if (!type.declaration.typeVariables.isEmpty()) { | 598 if (!type.declaration.typeVariables.isEmpty) { |
599 final typeVariables = []; | 599 final typeVariables = []; |
600 for (final typeVariable in type.declaration.typeVariables) { | 600 for (final typeVariable in type.declaration.typeVariables) { |
601 typeVariables.add(typeVariable.displayName); | 601 typeVariables.add(typeVariable.displayName); |
602 } | 602 } |
603 typeInfo[ARGS] = Strings.join(typeVariables, ', '); | 603 typeInfo[ARGS] = Strings.join(typeVariables, ', '); |
604 } | 604 } |
605 types.add(typeInfo); | 605 types.add(typeInfo); |
606 } | 606 } |
607 if (!types.isEmpty()) { | 607 if (!types.isEmpty) { |
608 libraryInfo[TYPES] = types; | 608 libraryInfo[TYPES] = types; |
609 } | 609 } |
610 | 610 |
611 libraryList.add(libraryInfo); | 611 libraryList.add(libraryInfo); |
612 } | 612 } |
613 | 613 |
614 List docMembersJson(Map<Object,MemberMirror> memberMap) { | 614 List docMembersJson(Map<Object,MemberMirror> memberMap) { |
615 final members = []; | 615 final members = []; |
616 for (MemberMirror member in orderByName(memberMap.getValues())) { | 616 for (MemberMirror member in orderByName(memberMap.getValues())) { |
617 if (!showPrivate && member.isPrivate) continue; | 617 if (!showPrivate && member.isPrivate) continue; |
618 | 618 |
619 var memberInfo = {}; | 619 var memberInfo = {}; |
620 if (member.isField) { | 620 if (member.isField) { |
621 memberInfo[KIND] = FIELD; | 621 memberInfo[KIND] = FIELD; |
622 } else { | 622 } else { |
623 MethodMirror method = member; | 623 MethodMirror method = member; |
624 if (method.isConstructor) { | 624 if (method.isConstructor) { |
625 memberInfo[KIND] = CONSTRUCTOR; | 625 memberInfo[KIND] = CONSTRUCTOR; |
626 } else if (method.isSetter) { | 626 } else if (method.isSetter) { |
627 memberInfo[KIND] = SETTER; | 627 memberInfo[KIND] = SETTER; |
628 } else if (method.isGetter) { | 628 } else if (method.isGetter) { |
629 memberInfo[KIND] = GETTER; | 629 memberInfo[KIND] = GETTER; |
630 } else { | 630 } else { |
631 memberInfo[KIND] = METHOD; | 631 memberInfo[KIND] = METHOD; |
632 } | 632 } |
633 if (method.parameters.isEmpty()) { | 633 if (method.parameters.isEmpty) { |
634 memberInfo[NO_PARAMS] = true; | 634 memberInfo[NO_PARAMS] = true; |
635 } | 635 } |
636 } | 636 } |
637 memberInfo[NAME] = member.displayName; | 637 memberInfo[NAME] = member.displayName; |
638 var anchor = memberAnchor(member); | 638 var anchor = memberAnchor(member); |
639 if (anchor != memberInfo[NAME]) { | 639 if (anchor != memberInfo[NAME]) { |
640 memberInfo[LINK_NAME] = anchor; | 640 memberInfo[LINK_NAME] = anchor; |
641 } | 641 } |
642 members.add(memberInfo); | 642 members.add(memberInfo); |
643 } | 643 } |
(...skipping 479 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1123 allInherited: allMethodsInherited); | 1123 allInherited: allMethodsInherited); |
1124 } | 1124 } |
1125 | 1125 |
1126 /** | 1126 /** |
1127 * Documents fields, getters, and setters as properties. | 1127 * Documents fields, getters, and setters as properties. |
1128 */ | 1128 */ |
1129 void docProperties(ObjectMirror host, String title, | 1129 void docProperties(ObjectMirror host, String title, |
1130 Map<String,MemberMirror> getters, | 1130 Map<String,MemberMirror> getters, |
1131 Map<String,MemberMirror> setters, | 1131 Map<String,MemberMirror> setters, |
1132 {bool allInherited}) { | 1132 {bool allInherited}) { |
1133 if (getters.isEmpty() && setters.isEmpty()) return; | 1133 if (getters.isEmpty && setters.isEmpty) return; |
1134 | 1134 |
1135 var nameSet = new Set<String>.from(getters.getKeys()); | 1135 var nameSet = new Set<String>.from(getters.getKeys()); |
1136 nameSet.addAll(setters.getKeys()); | 1136 nameSet.addAll(setters.getKeys()); |
1137 var nameList = new List<String>.from(nameSet); | 1137 var nameList = new List<String>.from(nameSet); |
1138 nameList.sort((String a, String b) { | 1138 nameList.sort((String a, String b) { |
1139 return a.toLowerCase().compareTo(b.toLowerCase()); | 1139 return a.toLowerCase().compareTo(b.toLowerCase()); |
1140 }); | 1140 }); |
1141 | 1141 |
1142 writeln('<div${allInherited ? ' class="inherited"' : ''}>'); | 1142 writeln('<div${allInherited ? ' class="inherited"' : ''}>'); |
1143 writeln('<h3>$title</h3>'); | 1143 writeln('<h3>$title</h3>'); |
(...skipping 507 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1651 for (final typeParam in type.declaration.typeVariables) { | 1651 for (final typeParam in type.declaration.typeVariables) { |
1652 if (showBounds && | 1652 if (showBounds && |
1653 (typeParam.bound != null) && | 1653 (typeParam.bound != null) && |
1654 !typeParam.bound.isObject) { | 1654 !typeParam.bound.isObject) { |
1655 final bound = typeName(typeParam.bound, showBounds: true); | 1655 final bound = typeName(typeParam.bound, showBounds: true); |
1656 typeParams.add('${typeParam.simpleName} extends $bound'); | 1656 typeParams.add('${typeParam.simpleName} extends $bound'); |
1657 } else { | 1657 } else { |
1658 typeParams.add(typeParam.simpleName); | 1658 typeParams.add(typeParam.simpleName); |
1659 } | 1659 } |
1660 } | 1660 } |
1661 if (typeParams.isEmpty()) { | 1661 if (typeParams.isEmpty) { |
1662 return type.simpleName; | 1662 return type.simpleName; |
1663 } | 1663 } |
1664 final params = Strings.join(typeParams, ', '); | 1664 final params = Strings.join(typeParams, ', '); |
1665 return '${type.simpleName}<$params>'; | 1665 return '${type.simpleName}<$params>'; |
1666 } | 1666 } |
1667 | 1667 |
1668 // See if it's an instantiation of a generic type. | 1668 // See if it's an instantiation of a generic type. |
1669 final typeArgs = type.typeArguments; | 1669 final typeArgs = type.typeArguments; |
1670 if (typeArgs.length > 0) { | 1670 if (typeArgs.length > 0) { |
1671 final args = Strings.join(typeArgs.map((arg) => typeName(arg)), ', '); | 1671 final args = Strings.join(typeArgs.map((arg) => typeName(arg)), ', '); |
(...skipping 169 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1841 | 1841 |
1842 class DocComment { | 1842 class DocComment { |
1843 final String text; | 1843 final String text; |
1844 | 1844 |
1845 /** | 1845 /** |
1846 * Non-null if the comment is inherited from another declaration. | 1846 * Non-null if the comment is inherited from another declaration. |
1847 */ | 1847 */ |
1848 final InterfaceMirror inheritedFrom; | 1848 final InterfaceMirror inheritedFrom; |
1849 | 1849 |
1850 DocComment(this.text, [this.inheritedFrom = null]) { | 1850 DocComment(this.text, [this.inheritedFrom = null]) { |
1851 assert(text != null && !text.trim().isEmpty()); | 1851 assert(text != null && !text.trim().isEmpty); |
1852 } | 1852 } |
1853 | 1853 |
1854 String get html => md.markdownToHtml(text); | 1854 String get html => md.markdownToHtml(text); |
1855 | 1855 |
1856 String toString() => text; | 1856 String toString() => text; |
1857 } | 1857 } |
OLD | NEW |