| 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 557 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 568 final List members = docMembersJson(library.declaredMembers); | 568 final List members = docMembersJson(library.declaredMembers); |
| 569 if (!members.isEmpty()) { | 569 if (!members.isEmpty()) { |
| 570 libraryInfo[MEMBERS] = members; | 570 libraryInfo[MEMBERS] = members; |
| 571 } | 571 } |
| 572 | 572 |
| 573 final types = []; | 573 final types = []; |
| 574 for (InterfaceMirror type in orderByName(library.types.getValues())) { | 574 for (InterfaceMirror type in orderByName(library.types.getValues())) { |
| 575 if (type.isPrivate) continue; | 575 if (type.isPrivate) continue; |
| 576 | 576 |
| 577 var typeInfo = {}; | 577 var typeInfo = {}; |
| 578 typeInfo[NAME] = type.simpleName; | 578 typeInfo[NAME] = type.displayName; |
| 579 if (type.isClass) { | 579 if (type.isClass) { |
| 580 typeInfo[KIND] = CLASS; | 580 typeInfo[KIND] = CLASS; |
| 581 } else if (type.isInterface) { | 581 } else if (type.isInterface) { |
| 582 typeInfo[KIND] = INTERFACE; | 582 typeInfo[KIND] = INTERFACE; |
| 583 } else { | 583 } else { |
| 584 assert(type.isTypedef); | 584 assert(type.isTypedef); |
| 585 typeInfo[KIND] = TYPEDEF; | 585 typeInfo[KIND] = TYPEDEF; |
| 586 } | 586 } |
| 587 final List typeMembers = docMembersJson(type.declaredMembers); | 587 final List typeMembers = docMembersJson(type.declaredMembers); |
| 588 if (!typeMembers.isEmpty()) { | 588 if (!typeMembers.isEmpty()) { |
| 589 typeInfo[MEMBERS] = typeMembers; | 589 typeInfo[MEMBERS] = typeMembers; |
| 590 } | 590 } |
| 591 | 591 |
| 592 if (!type.declaration.typeVariables.isEmpty()) { | 592 if (!type.declaration.typeVariables.isEmpty()) { |
| 593 final typeVariables = []; | 593 final typeVariables = []; |
| 594 for (final typeVariable in type.declaration.typeVariables) { | 594 for (final typeVariable in type.declaration.typeVariables) { |
| 595 typeVariables.add(typeVariable.simpleName); | 595 typeVariables.add(typeVariable.displayName); |
| 596 } | 596 } |
| 597 typeInfo[ARGS] = Strings.join(typeVariables, ', '); | 597 typeInfo[ARGS] = Strings.join(typeVariables, ', '); |
| 598 } | 598 } |
| 599 types.add(typeInfo); | 599 types.add(typeInfo); |
| 600 } | 600 } |
| 601 if (!types.isEmpty()) { | 601 if (!types.isEmpty()) { |
| 602 libraryInfo[TYPES] = types; | 602 libraryInfo[TYPES] = types; |
| 603 } | 603 } |
| 604 | 604 |
| 605 libraryList.add(libraryInfo); | 605 libraryList.add(libraryInfo); |
| 606 } | 606 } |
| 607 | 607 |
| 608 List docMembersJson(Map<Object,MemberMirror> memberMap) { | 608 List docMembersJson(Map<Object,MemberMirror> memberMap) { |
| 609 final members = []; | 609 final members = []; |
| 610 for (MemberMirror member in orderByName(memberMap.getValues())) { | 610 for (MemberMirror member in orderByName(memberMap.getValues())) { |
| 611 if (member.isPrivate) continue; | 611 if (member.isPrivate) continue; |
| 612 | 612 |
| 613 var memberInfo = {}; | 613 var memberInfo = {}; |
| 614 if (member.isField) { | 614 if (member.isField) { |
| 615 memberInfo[NAME] = member.simpleName; | |
| 616 memberInfo[KIND] = FIELD; | 615 memberInfo[KIND] = FIELD; |
| 617 } else { | 616 } else { |
| 618 MethodMirror method = member; | 617 MethodMirror method = member; |
| 619 if (method.isConstructor) { | 618 if (method.isConstructor) { |
| 620 if (method.constructorName != '') { | 619 memberInfo[KIND] = CONSTRUCTOR; |
| 621 memberInfo[NAME] = '${method.simpleName}.${method.constructorName}'; | |
| 622 memberInfo[KIND] = CONSTRUCTOR; | |
| 623 } else { | |
| 624 memberInfo[NAME] = member.simpleName; | |
| 625 memberInfo[KIND] = CONSTRUCTOR; | |
| 626 } | |
| 627 } else if (method.isOperator) { | |
| 628 memberInfo[NAME] = '${method.simpleName} ${method.operatorName}'; | |
| 629 memberInfo[KIND] = METHOD; | |
| 630 } else if (method.isSetter) { | 620 } else if (method.isSetter) { |
| 631 memberInfo[NAME] = member.simpleName; | |
| 632 memberInfo[KIND] = SETTER; | 621 memberInfo[KIND] = SETTER; |
| 633 } else if (method.isGetter) { | 622 } else if (method.isGetter) { |
| 634 memberInfo[NAME] = member.simpleName; | |
| 635 memberInfo[KIND] = GETTER; | 623 memberInfo[KIND] = GETTER; |
| 636 } else { | 624 } else { |
| 637 memberInfo[NAME] = member.simpleName; | |
| 638 memberInfo[KIND] = METHOD; | 625 memberInfo[KIND] = METHOD; |
| 639 } | 626 } |
| 640 } | 627 } |
| 628 memberInfo[NAME] = member.displayName; |
| 641 var anchor = memberAnchor(member); | 629 var anchor = memberAnchor(member); |
| 642 if (anchor != memberInfo[NAME]) { | 630 if (anchor != memberInfo[NAME]) { |
| 643 memberInfo[LINK_NAME] = anchor; | 631 memberInfo[LINK_NAME] = anchor; |
| 644 } | 632 } |
| 645 members.add(memberInfo); | 633 members.add(memberInfo); |
| 646 } | 634 } |
| 647 return members; | 635 return members; |
| 648 } | 636 } |
| 649 | 637 |
| 650 void docNavigation() { | 638 void docNavigation() { |
| (...skipping 263 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 914 typeSpan(supertypes[i]); | 902 typeSpan(supertypes[i]); |
| 915 write(' > '); | 903 write(' > '); |
| 916 } | 904 } |
| 917 | 905 |
| 918 // Write this class. | 906 // Write this class. |
| 919 typeSpan(type); | 907 typeSpan(type); |
| 920 writeln('</p>'); | 908 writeln('</p>'); |
| 921 } | 909 } |
| 922 | 910 |
| 923 listTypes(subtypes, 'Subclasses'); | 911 listTypes(subtypes, 'Subclasses'); |
| 924 listTypes(type.interfaces.getValues(), 'Implements'); | 912 listTypes(type.interfaces, 'Implements'); |
| 925 } else { | 913 } else { |
| 926 // Show the default class. | 914 // Show the default class. |
| 927 if (type.defaultType != null) { | 915 if (type.defaultType != null) { |
| 928 listTypes([type.defaultType], 'Default class'); | 916 listTypes([type.defaultType], 'Default class'); |
| 929 } | 917 } |
| 930 | 918 |
| 931 // List extended interfaces. | 919 // List extended interfaces. |
| 932 listTypes(type.interfaces.getValues(), 'Extends'); | 920 listTypes(type.interfaces, 'Extends'); |
| 933 | 921 |
| 934 // List subinterfaces and implementing classes. | 922 // List subinterfaces and implementing classes. |
| 935 final subinterfaces = []; | 923 final subinterfaces = []; |
| 936 final implementing = []; | 924 final implementing = []; |
| 937 | 925 |
| 938 for (final subtype in subtypes) { | 926 for (final subtype in subtypes) { |
| 939 if (subtype.isClass) { | 927 if (subtype.isClass) { |
| 940 implementing.add(subtype); | 928 implementing.add(subtype); |
| 941 } else { | 929 } else { |
| 942 subinterfaces.add(subtype); | 930 subinterfaces.add(subtype); |
| (...skipping 120 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1063 if (method.isConstructor) { | 1051 if (method.isConstructor) { |
| 1064 if (method.isFactory) { | 1052 if (method.isFactory) { |
| 1065 write('factory '); | 1053 write('factory '); |
| 1066 } else { | 1054 } else { |
| 1067 write(method.isConst ? 'const ' : 'new '); | 1055 write(method.isConst ? 'const ' : 'new '); |
| 1068 } | 1056 } |
| 1069 } else if (method.isAbstract) { | 1057 } else if (method.isAbstract) { |
| 1070 write('abstract '); | 1058 write('abstract '); |
| 1071 } | 1059 } |
| 1072 | 1060 |
| 1073 if (method.constructorName == null) { | 1061 if (!method.isConstructor) { |
| 1074 annotateType(host, method.returnType); | 1062 annotateType(host, method.returnType); |
| 1075 } | 1063 } |
| 1076 | 1064 |
| 1077 var name = method.simpleName; | 1065 var name = method.displayName; |
| 1078 // Translate specially-named methods: getters, setters, operators. | 1066 // Translate specially-named methods: getters, setters, operators. |
| 1079 if (method.isGetter) { | 1067 if (method.isGetter) { |
| 1080 // Getter. | 1068 // Getter. |
| 1081 name = 'get $name'; | 1069 name = 'get $name'; |
| 1082 } else if (method.isSetter) { | 1070 } else if (method.isSetter) { |
| 1083 // Setter. | 1071 // Setter. |
| 1084 name = 'set $name'; | 1072 name = 'set $name'; |
| 1085 } else if (method.isOperator) { | |
| 1086 name = 'operator ${method.operatorName}'; | |
| 1087 } | 1073 } |
| 1088 | 1074 |
| 1089 write('<strong>$name</strong>'); | 1075 write('<strong>$name</strong>'); |
| 1090 | 1076 |
| 1091 // Named constructors. | |
| 1092 if (method.constructorName != null && method.constructorName != '') { | |
| 1093 write('.'); | |
| 1094 write(method.constructorName); | |
| 1095 } | |
| 1096 | |
| 1097 docParamList(host, method.parameters); | 1077 docParamList(host, method.parameters); |
| 1098 | 1078 |
| 1099 var prefix = host is LibraryMirror ? '' : '${typeName(host)}.'; | 1079 var prefix = host is LibraryMirror ? '' : '${typeName(host)}.'; |
| 1100 write(''' <a class="anchor-link" href="#${memberAnchor(method)}" | 1080 write(''' <a class="anchor-link" href="#${memberAnchor(method)}" |
| 1101 title="Permalink to $prefix$name">#</a>'''); | 1081 title="Permalink to $prefix$name">#</a>'''); |
| 1102 writeln('</h4>'); | 1082 writeln('</h4>'); |
| 1103 | 1083 |
| 1104 docCode(method.location, getMethodComment(method), showCode: showCode); | 1084 docCode(method.location, getMethodComment(method), showCode: showCode); |
| 1105 | 1085 |
| 1106 writeln('</div>'); | 1086 writeln('</div>'); |
| (...skipping 152 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1259 } | 1239 } |
| 1260 | 1240 |
| 1261 /** Gets the URL for the documentation for [member]. */ | 1241 /** Gets the URL for the documentation for [member]. */ |
| 1262 String memberUrl(MemberMirror member) { | 1242 String memberUrl(MemberMirror member) { |
| 1263 String url = typeUrl(member.surroundingDeclaration); | 1243 String url = typeUrl(member.surroundingDeclaration); |
| 1264 return '$url#${memberAnchor(member)}'; | 1244 return '$url#${memberAnchor(member)}'; |
| 1265 } | 1245 } |
| 1266 | 1246 |
| 1267 /** Gets the anchor id for the document for [member]. */ | 1247 /** Gets the anchor id for the document for [member]. */ |
| 1268 String memberAnchor(MemberMirror member) { | 1248 String memberAnchor(MemberMirror member) { |
| 1269 if (member.isField) { | 1249 return member.simpleName; |
| 1270 return member.simpleName; | |
| 1271 } | |
| 1272 MethodMirror method = member; | |
| 1273 if (method.isConstructor) { | |
| 1274 if (method.constructorName == '') { | |
| 1275 return method.simpleName; | |
| 1276 } else { | |
| 1277 return '${method.simpleName}.${method.constructorName}'; | |
| 1278 } | |
| 1279 } else if (method.isOperator) { | |
| 1280 return '${method.simpleName} ${method.operatorName}'; | |
| 1281 } else if (method.isSetter) { | |
| 1282 return '${method.simpleName}='; | |
| 1283 } else { | |
| 1284 return method.simpleName; | |
| 1285 } | |
| 1286 } | 1250 } |
| 1287 | 1251 |
| 1288 /** | 1252 /** |
| 1289 * Creates a hyperlink. Handles turning the [href] into an appropriate | 1253 * Creates a hyperlink. Handles turning the [href] into an appropriate |
| 1290 * relative path from the current file. | 1254 * relative path from the current file. |
| 1291 */ | 1255 */ |
| 1292 String a(String href, String contents, [String css]) { | 1256 String a(String href, String contents, [String css]) { |
| 1293 // Mark outgoing external links, mainly so we can style them. | 1257 // Mark outgoing external links, mainly so we can style them. |
| 1294 final rel = isAbsolute(href) ? ' ref="external"' : ''; | 1258 final rel = isAbsolute(href) ? ' ref="external"' : ''; |
| 1295 final cssClass = css == null ? '' : ' class="$css"'; | 1259 final cssClass = css == null ? '' : ' class="$css"'; |
| (...skipping 173 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1469 if (parameter.simpleName == name) { | 1433 if (parameter.simpleName == name) { |
| 1470 final element = new md.Element.text('span', name); | 1434 final element = new md.Element.text('span', name); |
| 1471 element.attributes['class'] = 'param'; | 1435 element.attributes['class'] = 'param'; |
| 1472 return element; | 1436 return element; |
| 1473 } | 1437 } |
| 1474 } | 1438 } |
| 1475 } | 1439 } |
| 1476 | 1440 |
| 1477 // See if it's another member of the current type. | 1441 // See if it's another member of the current type. |
| 1478 if (currentType != null) { | 1442 if (currentType != null) { |
| 1479 final foundMember = findMirror(currentType.declaredMembers, name); | 1443 final foundMember = currentType.declaredMembers[name]; |
| 1480 if (foundMember != null) { | 1444 if (foundMember != null) { |
| 1481 return makeLink(memberUrl(foundMember)); | 1445 return makeLink(memberUrl(foundMember)); |
| 1482 } | 1446 } |
| 1483 } | 1447 } |
| 1484 | 1448 |
| 1485 // See if it's another type or a member of another type in the current | 1449 // See if it's another type or a member of another type in the current |
| 1486 // library. | 1450 // library. |
| 1487 if (currentLibrary != null) { | 1451 if (currentLibrary != null) { |
| 1488 // See if it's a constructor | 1452 // See if it's a constructor |
| 1489 final constructorLink = (() { | 1453 final constructorLink = (() { |
| 1490 final match = | 1454 final match = |
| 1491 new RegExp(r'new ([\w$]+)(?:\.([\w$]+))?').firstMatch(name); | 1455 new RegExp(r'new ([\w$]+)(?:\.([\w$]+))?').firstMatch(name); |
| 1492 if (match == null) return; | 1456 if (match == null) return; |
| 1493 InterfaceMirror foundtype = findMirror(currentLibrary.types, match[1]); | 1457 String typeName = match[1]; |
| 1458 InterfaceMirror foundtype = currentLibrary.types[typeName]; |
| 1494 if (foundtype == null) return; | 1459 if (foundtype == null) return; |
| 1460 String constructorName = |
| 1461 match[2] == null ? typeName : '$typeName.${match[2]}'; |
| 1495 final constructor = | 1462 final constructor = |
| 1496 findMirror(foundtype.constructors, | 1463 foundtype.constructors[constructorName]; |
| 1497 match[2] == null ? '' : match[2]); | |
| 1498 if (constructor == null) return; | 1464 if (constructor == null) return; |
| 1499 return makeLink(memberUrl(constructor)); | 1465 return makeLink(memberUrl(constructor)); |
| 1500 })(); | 1466 })(); |
| 1501 if (constructorLink != null) return constructorLink; | 1467 if (constructorLink != null) return constructorLink; |
| 1502 | 1468 |
| 1503 // See if it's a member of another type | 1469 // See if it's a member of another type |
| 1504 final foreignMemberLink = (() { | 1470 final foreignMemberLink = (() { |
| 1505 final match = new RegExp(r'([\w$]+)\.([\w$]+)').firstMatch(name); | 1471 final match = new RegExp(r'([\w$]+)\.([\w$]+)').firstMatch(name); |
| 1506 if (match == null) return; | 1472 if (match == null) return; |
| 1507 InterfaceMirror foundtype = findMirror(currentLibrary.types, match[1]); | 1473 InterfaceMirror foundtype = currentLibrary.types[match[1]]; |
| 1508 if (foundtype == null) return; | 1474 if (foundtype == null) return; |
| 1509 MemberMirror foundMember = findMirror(foundtype.declaredMembers, match[2
]); | 1475 MemberMirror foundMember = foundtype.declaredMembers[match[2]]; |
| 1510 if (foundMember == null) return; | 1476 if (foundMember == null) return; |
| 1511 return makeLink(memberUrl(foundMember)); | 1477 return makeLink(memberUrl(foundMember)); |
| 1512 })(); | 1478 })(); |
| 1513 if (foreignMemberLink != null) return foreignMemberLink; | 1479 if (foreignMemberLink != null) return foreignMemberLink; |
| 1514 | 1480 |
| 1515 InterfaceMirror foundType = findMirror(currentLibrary.types, name); | 1481 InterfaceMirror foundType = currentLibrary.types[name]; |
| 1516 if (foundType != null) { | 1482 if (foundType != null) { |
| 1517 return makeLink(typeUrl(foundType)); | 1483 return makeLink(typeUrl(foundType)); |
| 1518 } | 1484 } |
| 1519 | 1485 |
| 1520 // See if it's a top-level member in the current library. | 1486 // See if it's a top-level member in the current library. |
| 1521 MemberMirror foundMember = findMirror(currentLibrary.declaredMembers, name
); | 1487 MemberMirror foundMember = currentLibrary.declaredMembers[name]; |
| 1522 if (foundMember != null) { | 1488 if (foundMember != null) { |
| 1523 return makeLink(memberUrl(foundMember)); | 1489 return makeLink(memberUrl(foundMember)); |
| 1524 } | 1490 } |
| 1525 } | 1491 } |
| 1526 | 1492 |
| 1527 // TODO(rnystrom): Should also consider: | 1493 // TODO(rnystrom): Should also consider: |
| 1528 // * Names imported by libraries this library imports. | 1494 // * Names imported by libraries this library imports. |
| 1529 // * Type parameters of the enclosing type. | 1495 // * Type parameters of the enclosing type. |
| 1530 | 1496 |
| 1531 return new md.Element.text('code', name); | 1497 return new md.Element.text('code', name); |
| (...skipping 43 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1575 | 1541 |
| 1576 /** | 1542 /** |
| 1577 * Used to report an unexpected error in the DartDoc tool or the | 1543 * Used to report an unexpected error in the DartDoc tool or the |
| 1578 * underlying data | 1544 * underlying data |
| 1579 */ | 1545 */ |
| 1580 class InternalError { | 1546 class InternalError { |
| 1581 final String message; | 1547 final String message; |
| 1582 const InternalError(this.message); | 1548 const InternalError(this.message); |
| 1583 String toString() => "InternalError: '$message'"; | 1549 String toString() => "InternalError: '$message'"; |
| 1584 } | 1550 } |
| OLD | NEW |