| 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 |