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 * This generates the reference documentation for the core libraries that come | 6 * This generates the reference documentation for the core libraries that come |
7 * with dart. It is built on top of dartdoc, which is a general-purpose library | 7 * with dart. It is built on top of dartdoc, which is a general-purpose library |
8 * for generating docs from any Dart code. This library extends that to include | 8 * for generating docs from any Dart code. This library extends that to include |
9 * additional information and styling specific to our standard library. | 9 * additional information and styling specific to our standard library. |
10 * | 10 * |
11 * Usage: | 11 * Usage: |
12 * | 12 * |
13 * $ dart apidoc.dart [--out=<output directory>] | 13 * $ dart apidoc.dart [--out=<output directory>] |
14 */ | 14 */ |
15 library apidoc; | 15 library apidoc; |
16 | 16 |
17 import 'dart:async'; | 17 import 'dart:async'; |
18 import 'dart:convert'; | 18 import 'dart:convert'; |
19 import 'dart:io'; | 19 import 'dart:io'; |
20 | 20 |
21 import 'html_diff.dart'; | 21 import 'html_diff.dart'; |
22 | 22 |
23 // TODO(rnystrom): Use "package:" URL (#4968). | 23 // TODO(rnystrom): Use "package:" URL (#4968). |
24 import '../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors.dart'; | 24 import '../../sdk/lib/_internal/compiler/implementation/mirrors/source_mirrors.d
art'; |
25 import '../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dar
t'; | 25 import '../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dar
t'; |
26 import '../../sdk/lib/_internal/compiler/implementation/filenames.dart'; | 26 import '../../sdk/lib/_internal/compiler/implementation/filenames.dart'; |
27 import '../../sdk/lib/_internal/dartdoc/lib/dartdoc.dart'; | 27 import '../../sdk/lib/_internal/dartdoc/lib/dartdoc.dart'; |
28 import '../../sdk/lib/_internal/libraries.dart'; | 28 import '../../sdk/lib/_internal/libraries.dart'; |
29 import 'package:path/path.dart' as path; | 29 import 'package:path/path.dart' as path; |
30 | 30 |
31 HtmlDiff _diff; | 31 HtmlDiff _diff; |
32 | 32 |
33 void main(List<String> args) { | 33 void main(List<String> args) { |
34 int mode = MODE_STATIC; | 34 int mode = MODE_STATIC; |
(...skipping 263 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
298 | 298 |
299 DocComment getLibraryComment(LibraryMirror library) { | 299 DocComment getLibraryComment(LibraryMirror library) { |
300 return super.getLibraryComment(library); | 300 return super.getLibraryComment(library); |
301 } | 301 } |
302 | 302 |
303 DocComment getTypeComment(TypeMirror type) { | 303 DocComment getTypeComment(TypeMirror type) { |
304 return _mergeDocs( | 304 return _mergeDocs( |
305 includeMdnTypeComment(type), super.getTypeComment(type)); | 305 includeMdnTypeComment(type), super.getTypeComment(type)); |
306 } | 306 } |
307 | 307 |
308 DocComment getMemberComment(MemberMirror member) { | 308 DocComment getMemberComment(DeclarationMirror member) { |
309 return _mergeDocs( | 309 return _mergeDocs( |
310 includeMdnMemberComment(member), super.getMemberComment(member)); | 310 includeMdnMemberComment(member), super.getMemberComment(member)); |
311 } | 311 } |
312 | 312 |
313 DocComment _mergeDocs(MdnComment mdnComment, | 313 DocComment _mergeDocs(MdnComment mdnComment, |
314 DocComment fileComment) { | 314 DocComment fileComment) { |
315 // Otherwise, prefer comment from the (possibly generated) Dart file. | 315 // Otherwise, prefer comment from the (possibly generated) Dart file. |
316 if (fileComment != null) return fileComment; | 316 if (fileComment != null) return fileComment; |
317 | 317 |
318 // Finally, fallback on MDN if available. | 318 // Finally, fallback on MDN if available. |
(...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
353 <a href="$CONTRIB">contributing</a> to | 353 <a href="$CONTRIB">contributing</a> to |
354 <a href="$MDN">The Mozilla Developer Network</a>. | 354 <a href="$MDN">The Mozilla Developer Network</a>. |
355 </p> | 355 </p> |
356 '''); | 356 '''); |
357 } | 357 } |
358 } | 358 } |
359 | 359 |
360 MdnComment lookupMdnComment(Mirror mirror) { | 360 MdnComment lookupMdnComment(Mirror mirror) { |
361 if (mirror is TypeMirror) { | 361 if (mirror is TypeMirror) { |
362 return includeMdnTypeComment(mirror); | 362 return includeMdnTypeComment(mirror); |
363 } else if (mirror is MemberMirror) { | 363 } else if (mirror is MethodMirror || mirror is VariableMirror) { |
364 return includeMdnMemberComment(mirror); | 364 return includeMdnMemberComment(mirror); |
365 } else { | 365 } else { |
366 return null; | 366 return null; |
367 } | 367 } |
368 } | 368 } |
369 | 369 |
370 /** | 370 /** |
371 * Gets the MDN-scraped docs for [type], or `null` if this type isn't | 371 * Gets the MDN-scraped docs for [type], or `null` if this type isn't |
372 * scraped from MDN. | 372 * scraped from MDN. |
373 */ | 373 */ |
374 MdnComment includeMdnTypeComment(TypeMirror type) { | 374 MdnComment includeMdnTypeComment(TypeMirror type) { |
375 if (_mdnTypeNamesToSkip.contains(type.simpleName)) { | 375 if (_mdnTypeNamesToSkip.contains(type.simpleName)) { |
376 return null; | 376 return null; |
377 } | 377 } |
378 | 378 |
379 var typeString = ''; | 379 var typeString = ''; |
380 if (HTML_LIBRARY_URIS.contains(type.library.uri)) { | 380 if (HTML_LIBRARY_URIS.contains(getLibrary(type).uri)) { |
381 // If it's an HTML type, try to map it to a base DOM type so we can find | 381 // If it's an HTML type, try to map it to a base DOM type so we can find |
382 // the MDN docs. | 382 // the MDN docs. |
383 final domTypes = _diff.htmlTypesToDom[type.qualifiedName]; | 383 final domTypes = _diff.htmlTypesToDom[type.qualifiedName]; |
384 | 384 |
385 // Couldn't find a DOM type. | 385 // Couldn't find a DOM type. |
386 if ((domTypes == null) || (domTypes.length != 1)) return null; | 386 if ((domTypes == null) || (domTypes.length != 1)) return null; |
387 | 387 |
388 // Use the corresponding DOM type when searching MDN. | 388 // Use the corresponding DOM type when searching MDN. |
389 // TODO(rnystrom): Shame there isn't a simpler way to get the one item | 389 // TODO(rnystrom): Shame there isn't a simpler way to get the one item |
390 // out of a singleton Set. | 390 // out of a singleton Set. |
(...skipping 13 matching lines...) Expand all Loading... |
404 if (mdnType['summary'].trim().isEmpty) return null; | 404 if (mdnType['summary'].trim().isEmpty) return null; |
405 | 405 |
406 // Remember which MDN page we're using so we can attribute it. | 406 // Remember which MDN page we're using so we can attribute it. |
407 return new MdnComment(mdnType['summary'], mdnType['srcUrl']); | 407 return new MdnComment(mdnType['summary'], mdnType['srcUrl']); |
408 } | 408 } |
409 | 409 |
410 /** | 410 /** |
411 * Gets the MDN-scraped docs for [member], or `null` if this type isn't | 411 * Gets the MDN-scraped docs for [member], or `null` if this type isn't |
412 * scraped from MDN. | 412 * scraped from MDN. |
413 */ | 413 */ |
414 MdnComment includeMdnMemberComment(MemberMirror member) { | 414 MdnComment includeMdnMemberComment(DeclarationMirror member) { |
415 var library = findLibrary(member); | 415 var library = getLibrary(member); |
416 var memberString = ''; | 416 var memberString = ''; |
417 if (HTML_LIBRARY_URIS.contains(library.uri)) { | 417 if (HTML_LIBRARY_URIS.contains(library.uri)) { |
418 // If it's an HTML type, try to map it to a DOM type name so we can find | 418 // If it's an HTML type, try to map it to a DOM type name so we can find |
419 // the MDN docs. | 419 // the MDN docs. |
420 final domMembers = _diff.htmlToDom[member.qualifiedName]; | 420 final domMembers = _diff.htmlToDom[member.qualifiedName]; |
421 | 421 |
422 // Couldn't find a DOM type. | 422 // Couldn't find a DOM type. |
423 if ((domMembers == null) || (domMembers.length != 1)) return null; | 423 if ((domMembers == null) || (domMembers.length != 1)) return null; |
424 | 424 |
425 // Use the corresponding DOM member when searching MDN. | 425 // Use the corresponding DOM member when searching MDN. |
(...skipping 31 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
457 if (mdnMember['help'].trim().isEmpty) return null; | 457 if (mdnMember['help'].trim().isEmpty) return null; |
458 | 458 |
459 // Remember which MDN page we're using so we can attribute it. | 459 // Remember which MDN page we're using so we can attribute it. |
460 return new MdnComment(mdnMember['help'], mdnType['srcUrl']); | 460 return new MdnComment(mdnMember['help'], mdnType['srcUrl']); |
461 } | 461 } |
462 | 462 |
463 /** | 463 /** |
464 * Returns a link to [member], relative to a type page that may be in a | 464 * Returns a link to [member], relative to a type page that may be in a |
465 * different library than [member]. | 465 * different library than [member]. |
466 */ | 466 */ |
467 String _linkMember(MemberMirror member) { | 467 String _linkMember(DeclarationMirror member) { |
468 final typeName = member.owner.simpleName; | 468 final typeName = member.owner.simpleName; |
469 var memberName = '$typeName.${member.simpleName}'; | 469 var memberName = '$typeName.${member.simpleName}'; |
470 if (member is MethodMirror && member.isConstructor) { | 470 if (member is MethodMirror && member.isConstructor) { |
471 final separator = member.constructorName == '' ? '' : '.'; | 471 final separator = member.constructorName == '' ? '' : '.'; |
472 memberName = 'new $typeName$separator${member.constructorName}'; | 472 memberName = 'new $typeName$separator${member.constructorName}'; |
473 } | 473 } |
474 | 474 |
475 return a(memberUrl(member), memberName); | 475 return a(memberUrl(member), memberName); |
476 } | 476 } |
477 } | 477 } |
478 | 478 |
OLD | NEW |