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 1065 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1076 } | 1076 } |
1077 } | 1077 } |
1078 | 1078 |
1079 bool allMethodsInherited = true; | 1079 bool allMethodsInherited = true; |
1080 bool allPropertiesInherited = true; | 1080 bool allPropertiesInherited = true; |
1081 bool allOperatorsInherited = true; | 1081 bool allOperatorsInherited = true; |
1082 memberMap.forEach((_, MemberMirror member) { | 1082 memberMap.forEach((_, MemberMirror member) { |
1083 if (member is MethodMirror) { | 1083 if (member is MethodMirror) { |
1084 if (member.isGetter) { | 1084 if (member.isGetter) { |
1085 instanceGetters[member.displayName] = member; | 1085 instanceGetters[member.displayName] = member; |
1086 if (member.surroundingDeclaration == host) { | 1086 if (member.owner == host) { |
1087 allPropertiesInherited = false; | 1087 allPropertiesInherited = false; |
1088 } | 1088 } |
1089 } else if (member.isSetter) { | 1089 } else if (member.isSetter) { |
1090 instanceSetters[member.displayName] = member; | 1090 instanceSetters[member.displayName] = member; |
1091 if (member.surroundingDeclaration == host) { | 1091 if (member.owner == host) { |
1092 allPropertiesInherited = false; | 1092 allPropertiesInherited = false; |
1093 } | 1093 } |
1094 } else if (member.isOperator) { | 1094 } else if (member.isOperator) { |
1095 instanceOperators.add(member); | 1095 instanceOperators.add(member); |
1096 if (member.surroundingDeclaration == host) { | 1096 if (member.owner == host) { |
1097 allOperatorsInherited = false; | 1097 allOperatorsInherited = false; |
1098 } | 1098 } |
1099 } else { | 1099 } else { |
1100 instanceMethods.add(member); | 1100 instanceMethods.add(member); |
1101 if (member.surroundingDeclaration == host) { | 1101 if (member.owner == host) { |
1102 allMethodsInherited = false; | 1102 allMethodsInherited = false; |
1103 } | 1103 } |
1104 } | 1104 } |
1105 } else if (member is FieldMirror) { | 1105 } else if (member is FieldMirror) { |
1106 instanceGetters[member.displayName] = member; | 1106 instanceGetters[member.displayName] = member; |
1107 if (member.surroundingDeclaration == host) { | 1107 if (member.owner == host) { |
1108 allPropertiesInherited = false; | 1108 allPropertiesInherited = false; |
1109 } | 1109 } |
1110 } | 1110 } |
1111 }); | 1111 }); |
1112 | 1112 |
1113 instanceOperators.sort((MethodMirror a, MethodMirror b) { | 1113 instanceOperators.sort((MethodMirror a, MethodMirror b) { |
1114 return operatorOrderMap[a.simpleName].compareTo( | 1114 return operatorOrderMap[a.simpleName].compareTo( |
1115 operatorOrderMap[b.simpleName]); | 1115 operatorOrderMap[b.simpleName]); |
1116 }); | 1116 }); |
1117 | 1117 |
(...skipping 44 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1162 assert(getter is MethodMirror); | 1162 assert(getter is MethodMirror); |
1163 docProperty(host, getter, null); | 1163 docProperty(host, getter, null); |
1164 } | 1164 } |
1165 } else if (getter == null) { | 1165 } else if (getter == null) { |
1166 // We only have a setter => Document as a method. | 1166 // We only have a setter => Document as a method. |
1167 assert(setter is MethodMirror); | 1167 assert(setter is MethodMirror); |
1168 docMethod(host, setter); | 1168 docMethod(host, setter); |
1169 } else { | 1169 } else { |
1170 DocComment getterComment = getMemberComment(getter); | 1170 DocComment getterComment = getMemberComment(getter); |
1171 DocComment setterComment = getMemberComment(setter); | 1171 DocComment setterComment = getMemberComment(setter); |
1172 if (getter.surroundingDeclaration !== setter.surroundingDeclaration || | 1172 if (getter.owner !== setter.owner || |
1173 getterComment != null && setterComment != null) { | 1173 getterComment != null && setterComment != null) { |
1174 // Both have comments or are not declared in the same class | 1174 // Both have comments or are not declared in the same class |
1175 // => Documents separately. | 1175 // => Documents separately. |
1176 if (getter is FieldMirror) { | 1176 if (getter is FieldMirror) { |
1177 // Document field as a getter (setter is inherited). | 1177 // Document field as a getter (setter is inherited). |
1178 docField(host, getter, asGetter: true); | 1178 docField(host, getter, asGetter: true); |
1179 } else { | 1179 } else { |
1180 docMethod(host, getter); | 1180 docMethod(host, getter); |
1181 } | 1181 } |
1182 if (setter is FieldMirror) { | 1182 if (setter is FieldMirror) { |
(...skipping 50 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1233 if (member.isGetter) { | 1233 if (member.isGetter) { |
1234 // Getter. | 1234 // Getter. |
1235 name = 'get $name'; | 1235 name = 'get $name'; |
1236 } else if (member.isSetter) { | 1236 } else if (member.isSetter) { |
1237 // Setter. | 1237 // Setter. |
1238 name = 'set $name'; | 1238 name = 'set $name'; |
1239 } | 1239 } |
1240 } | 1240 } |
1241 | 1241 |
1242 bool showCode = includeSource && !isAbstract; | 1242 bool showCode = includeSource && !isAbstract; |
1243 bool inherited = host != member.surroundingDeclaration; | 1243 bool inherited = host != member.owner; |
1244 | 1244 |
1245 writeln('<div class="method${inherited ? ' inherited': ''}">' | 1245 writeln('<div class="method${inherited ? ' inherited': ''}">' |
1246 '<h4 id="${memberAnchor(member)}">'); | 1246 '<h4 id="${memberAnchor(member)}">'); |
1247 | 1247 |
1248 if (showCode) { | 1248 if (showCode) { |
1249 writeln('<button class="show-code">Code</button>'); | 1249 writeln('<button class="show-code">Code</button>'); |
1250 } | 1250 } |
1251 | 1251 |
1252 if (member is MethodMirror) { | 1252 if (member is MethodMirror) { |
1253 if (member.isConstructor) { | 1253 if (member.isConstructor) { |
(...skipping 33 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1287 } | 1287 } |
1288 } | 1288 } |
1289 | 1289 |
1290 var prefix = host is LibraryMirror ? '' : '${typeName(host)}.'; | 1290 var prefix = host is LibraryMirror ? '' : '${typeName(host)}.'; |
1291 write(''' <a class="anchor-link" href="#${memberAnchor(member)}" | 1291 write(''' <a class="anchor-link" href="#${memberAnchor(member)}" |
1292 title="Permalink to $prefix$name">#</a>'''); | 1292 title="Permalink to $prefix$name">#</a>'''); |
1293 writeln('</h4>'); | 1293 writeln('</h4>'); |
1294 | 1294 |
1295 if (inherited) { | 1295 if (inherited) { |
1296 write('<div class="inherited-from">inherited from '); | 1296 write('<div class="inherited-from">inherited from '); |
1297 annotateType(host, member.surroundingDeclaration); | 1297 annotateType(host, member.owner); |
1298 write('</div>'); | 1298 write('</div>'); |
1299 } | 1299 } |
1300 | 1300 |
1301 writeln('<div class="doc">'); | 1301 writeln('<div class="doc">'); |
1302 docComment(host, getMemberComment(member)); | 1302 docComment(host, getMemberComment(member)); |
1303 if (showCode) { | 1303 if (showCode) { |
1304 docCode(member.location); | 1304 docCode(member.location); |
1305 } | 1305 } |
1306 writeln('</div>'); | 1306 writeln('</div>'); |
1307 | 1307 |
(...skipping 16 matching lines...) Expand all Loading... |
1324 * [host]. If [getter] is a [FieldMirror], [setter] must be [:null:]. | 1324 * [host]. If [getter] is a [FieldMirror], [setter] must be [:null:]. |
1325 * Otherwise, if [getter] is a [MethodMirror], the property is considered | 1325 * Otherwise, if [getter] is a [MethodMirror], the property is considered |
1326 * final if [setter] is [:null:]. | 1326 * final if [setter] is [:null:]. |
1327 */ | 1327 */ |
1328 void docProperty(ObjectMirror host, | 1328 void docProperty(ObjectMirror host, |
1329 MemberMirror getter, MemberMirror setter) { | 1329 MemberMirror getter, MemberMirror setter) { |
1330 assert(getter != null); | 1330 assert(getter != null); |
1331 _totalMembers++; | 1331 _totalMembers++; |
1332 _currentMember = getter; | 1332 _currentMember = getter; |
1333 | 1333 |
1334 bool inherited = host != getter.surroundingDeclaration; | 1334 bool inherited = host != getter.owner; |
1335 | 1335 |
1336 writeln('<div class="field${inherited ? ' inherited' : ''}">' | 1336 writeln('<div class="field${inherited ? ' inherited' : ''}">' |
1337 '<h4 id="${memberAnchor(getter)}">'); | 1337 '<h4 id="${memberAnchor(getter)}">'); |
1338 | 1338 |
1339 if (includeSource) { | 1339 if (includeSource) { |
1340 writeln('<button class="show-code">Code</button>'); | 1340 writeln('<button class="show-code">Code</button>'); |
1341 } | 1341 } |
1342 | 1342 |
1343 bool isConst = false; | 1343 bool isConst = false; |
1344 bool isFinal; | 1344 bool isFinal; |
(...skipping 22 matching lines...) Expand all Loading... |
1367 write( | 1367 write( |
1368 ''' | 1368 ''' |
1369 <strong>${getter.simpleName}</strong> <a class="anchor-link" | 1369 <strong>${getter.simpleName}</strong> <a class="anchor-link" |
1370 href="#${memberAnchor(getter)}" | 1370 href="#${memberAnchor(getter)}" |
1371 title="Permalink to $prefix${getter.simpleName}">#</a> | 1371 title="Permalink to $prefix${getter.simpleName}">#</a> |
1372 </h4> | 1372 </h4> |
1373 '''); | 1373 '''); |
1374 | 1374 |
1375 if (inherited) { | 1375 if (inherited) { |
1376 write('<div class="inherited-from">inherited from '); | 1376 write('<div class="inherited-from">inherited from '); |
1377 annotateType(host, getter.surroundingDeclaration); | 1377 annotateType(host, getter.owner); |
1378 write('</div>'); | 1378 write('</div>'); |
1379 } | 1379 } |
1380 | 1380 |
1381 DocComment comment = getMemberComment(getter); | 1381 DocComment comment = getMemberComment(getter); |
1382 if (comment == null && setter != null) { | 1382 if (comment == null && setter != null) { |
1383 comment = getMemberComment(setter); | 1383 comment = getMemberComment(setter); |
1384 } | 1384 } |
1385 writeln('<div class="doc">'); | 1385 writeln('<div class="doc">'); |
1386 docComment(host, comment); | 1386 docComment(host, comment); |
1387 docCode(getter.location); | 1387 docCode(getter.location); |
(...skipping 82 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1470 * Get the doc comment associated with the given member. | 1470 * Get the doc comment associated with the given member. |
1471 * | 1471 * |
1472 * If no comment was found on the member, the hierarchy is traversed to find | 1472 * If no comment was found on the member, the hierarchy is traversed to find |
1473 * an inherited comment, favouring comments inherited from classes over | 1473 * an inherited comment, favouring comments inherited from classes over |
1474 * comments inherited from interfaces. | 1474 * comments inherited from interfaces. |
1475 */ | 1475 */ |
1476 DocComment getMemberComment(MemberMirror member) { | 1476 DocComment getMemberComment(MemberMirror member) { |
1477 String comment = _comments.find(member.location); | 1477 String comment = _comments.find(member.location); |
1478 ClassMirror inheritedFrom = null; | 1478 ClassMirror inheritedFrom = null; |
1479 if (comment == null) { | 1479 if (comment == null) { |
1480 if (member.surroundingDeclaration is ClassMirror) { | 1480 if (member.owner is ClassMirror) { |
1481 var iterable = | 1481 var iterable = |
1482 new HierarchyIterable(member.surroundingDeclaration, | 1482 new HierarchyIterable(member.owner, |
1483 includeType: false); | 1483 includeType: false); |
1484 for (ClassMirror type in iterable) { | 1484 for (ClassMirror type in iterable) { |
1485 var inheritedMember = type.declaredMembers[member.simpleName]; | 1485 var inheritedMember = type.declaredMembers[member.simpleName]; |
1486 if (inheritedMember is MemberMirror) { | 1486 if (inheritedMember is MemberMirror) { |
1487 comment = _comments.find(inheritedMember.location); | 1487 comment = _comments.find(inheritedMember.location); |
1488 if (comment != null) { | 1488 if (comment != null) { |
1489 inheritedFrom = type; | 1489 inheritedFrom = type; |
1490 break; | 1490 break; |
1491 } | 1491 } |
1492 } | 1492 } |
(...skipping 39 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1532 assert (type is TypeMirror); | 1532 assert (type is TypeMirror); |
1533 // Always get the generic type to strip off any type parameters or | 1533 // Always get the generic type to strip off any type parameters or |
1534 // arguments. If the type isn't generic, genericType returns `this`, so it | 1534 // arguments. If the type isn't generic, genericType returns `this`, so it |
1535 // works for non-generic types too. | 1535 // works for non-generic types too. |
1536 return '${sanitize(displayName(type.library))}/' | 1536 return '${sanitize(displayName(type.library))}/' |
1537 '${type.declaration.simpleName}.html'; | 1537 '${type.declaration.simpleName}.html'; |
1538 } | 1538 } |
1539 | 1539 |
1540 /** Gets the URL for the documentation for [member]. */ | 1540 /** Gets the URL for the documentation for [member]. */ |
1541 String memberUrl(MemberMirror member) { | 1541 String memberUrl(MemberMirror member) { |
1542 String url = typeUrl(member.surroundingDeclaration); | 1542 String url = typeUrl(member.owner); |
1543 return '$url#${memberAnchor(member)}'; | 1543 return '$url#${memberAnchor(member)}'; |
1544 } | 1544 } |
1545 | 1545 |
1546 /** Gets the anchor id for the document for [member]. */ | 1546 /** Gets the anchor id for the document for [member]. */ |
1547 String memberAnchor(MemberMirror member) { | 1547 String memberAnchor(MemberMirror member) { |
1548 return member.simpleName; | 1548 return member.simpleName; |
1549 } | 1549 } |
1550 | 1550 |
1551 /** | 1551 /** |
1552 * Creates a hyperlink. Handles turning the [href] into an appropriate | 1552 * Creates a hyperlink. Handles turning the [href] into an appropriate |
(...skipping 304 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1857 final ClassMirror inheritedFrom; | 1857 final ClassMirror inheritedFrom; |
1858 | 1858 |
1859 DocComment(this.text, [this.inheritedFrom = null]) { | 1859 DocComment(this.text, [this.inheritedFrom = null]) { |
1860 assert(text != null && !text.trim().isEmpty); | 1860 assert(text != null && !text.trim().isEmpty); |
1861 } | 1861 } |
1862 | 1862 |
1863 String get html => md.markdownToHtml(text); | 1863 String get html => md.markdownToHtml(text); |
1864 | 1864 |
1865 String toString() => text; | 1865 String toString() => text; |
1866 } | 1866 } |
OLD | NEW |