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 * |
(...skipping 430 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
441 </p> | 441 </p> |
442 '''); | 442 '''); |
443 } | 443 } |
444 } | 444 } |
445 | 445 |
446 /** | 446 /** |
447 * Gets the MDN-scraped docs for [type], or `null` if this type isn't | 447 * Gets the MDN-scraped docs for [type], or `null` if this type isn't |
448 * scraped from MDN. | 448 * scraped from MDN. |
449 */ | 449 */ |
450 includeMdnTypeComment(TypeMirror type) { | 450 includeMdnTypeComment(TypeMirror type) { |
451 var typeString = ''; | |
451 if (type.library.simpleName == HTML_LIBRARY_NAME) { | 452 if (type.library.simpleName == HTML_LIBRARY_NAME) { |
452 // If it's an HTML type, try to map it to a base DOM type so we can find | 453 // If it's an HTML type, try to map it to a base DOM type so we can find |
453 // the MDN docs. | 454 // the MDN docs. |
454 final domTypes = _diff.htmlTypesToDom[type.qualifiedName]; | 455 final domTypes = _diff.htmlTypesToDom[type.qualifiedName]; |
455 | 456 |
456 // Couldn't find a DOM type. | 457 // Couldn't find a DOM type. |
457 if ((domTypes == null) || (domTypes.length != 1)) return null; | 458 if ((domTypes == null) || (domTypes.length != 1)) return null; |
458 | 459 |
459 // Use the corresponding DOM type when searching MDN. | 460 // Use the corresponding DOM type when searching MDN. |
460 // TODO(rnystrom): Shame there isn't a simpler way to get the one item | 461 // TODO(rnystrom): Shame there isn't a simpler way to get the one item |
461 // out of a singleton Set. | 462 // out of a singleton Set. |
462 type = domTypes.iterator().next(); | 463 typeString = domTypes.iterator().next(); |
463 } else if (type.library.simpleName != DOM_LIBRARY_NAME) { | |
464 // Not a DOM type. | |
465 return null; | |
466 } | 464 } |
467 | 465 |
468 final mdnType = mdn[type.simpleName]; | 466 final mdnType = mdn[typeString]; |
eub
2012/09/05 21:28:11
I may be paranoid but I have a worry that mdn['']
Emily Fortuna
2012/09/05 21:57:26
Good point. I've added an else branch above so tha
| |
469 if (mdnType == null) return null; | 467 if (mdnType == null) return null; |
470 if (mdnType['skipped'] != null) return null; | 468 if (mdnType['skipped'] != null) return null; |
471 | 469 |
472 // Remember which MDN page we're using so we can attribute it. | 470 // Remember which MDN page we're using so we can attribute it. |
473 mdnUrl = mdnType['srcUrl']; | 471 mdnUrl = mdnType['srcUrl']; |
474 return mdnType['summary']; | 472 return mdnType['summary']; |
475 } | 473 } |
476 | 474 |
477 /** | 475 /** |
478 * Gets the MDN-scraped docs for [member], or `null` if this type isn't | 476 * Gets the MDN-scraped docs for [member], or `null` if this type isn't |
479 * scraped from MDN. | 477 * scraped from MDN. |
480 */ | 478 */ |
481 includeMdnMemberComment(MemberMirror member) { | 479 includeMdnMemberComment(MemberMirror member) { |
482 var library = findLibrary(member); | 480 var library = findLibrary(member); |
481 var memberString = ''; | |
483 if (library.simpleName == HTML_LIBRARY_NAME) { | 482 if (library.simpleName == HTML_LIBRARY_NAME) { |
484 // If it's an HTML type, try to map it to a base DOM type so we can find | 483 // If it's an HTML type, try to map it to a DOM name type so we can find |
eub
2012/09/05 21:28:11
"DOM type name"?
Emily Fortuna
2012/09/05 21:57:26
Done.
| |
485 // the MDN docs. | 484 // the MDN docs. |
486 final domMembers = _diff.htmlToDom[member.qualifiedName]; | 485 final domMembers = _diff.htmlToDom[member.qualifiedName]; |
487 | 486 |
488 // Couldn't find a DOM type. | 487 // Couldn't find a DOM type. |
489 if ((domMembers == null) || (domMembers.length != 1)) return null; | 488 if ((domMembers == null) || (domMembers.length != 1)) return null; |
490 | 489 |
491 // Use the corresponding DOM member when searching MDN. | 490 // Use the corresponding DOM member when searching MDN. |
492 // TODO(rnystrom): Shame there isn't a simpler way to get the one item | 491 // TODO(rnystrom): Shame there isn't a simpler way to get the one item |
493 // out of a singleton Set. | 492 // out of a singleton Set. |
494 member = domMembers.iterator().next(); | 493 memberString = domMembers.iterator().next(); |
495 } else if (library.simpleName != DOM_LIBRARY_NAME) { | |
496 // Not a DOM type. | |
497 return null; | |
498 } | 494 } |
499 | 495 |
500 // Ignore top-level functions. | 496 // Ignore top-level functions. |
501 if (member.isTopLevel) return null; | 497 if (member.isTopLevel) return null; |
502 | 498 |
503 final mdnType = mdn[member.surroundingDeclaration.simpleName]; | |
504 if (mdnType == null) return null; | |
505 var nameToFind = member.simpleName; | |
506 var mdnMember = null; | 499 var mdnMember = null; |
507 for (final candidateMember in mdnType['members']) { | 500 var mdnType = null; |
508 if (candidateMember['name'] == nameToFind) { | 501 var pieces = memberString.split('.'); |
509 mdnMember = candidateMember; | 502 if (pieces.length == 2) { |
510 break; | 503 mdnType = mdn[pieces[0]]; |
504 if (mdnType == null) return null; | |
eub
2012/09/05 21:28:11
Can this happen from split()?
Emily Fortuna
2012/09/05 21:57:26
Yes, if we try to look up in the mdn dictionary a
| |
505 var nameToFind = pieces[1]; | |
506 for (final candidateMember in mdnType['members']) { | |
507 if (candidateMember['name'] == nameToFind) { | |
508 mdnMember = candidateMember; | |
509 break; | |
510 } | |
511 } | 511 } |
512 } | 512 } |
513 | 513 |
514 if (mdnMember == null) return null; | 514 if (mdnMember == null) return null; |
515 | 515 |
516 // Remember which MDN page we're using so we can attribute it. | 516 // Remember which MDN page we're using so we can attribute it. |
517 mdnUrl = mdnType['srcUrl']; | 517 mdnUrl = mdnType['srcUrl']; |
518 return mdnMember['help']; | 518 return mdnMember['help']; |
519 } | 519 } |
520 | 520 |
521 /** | 521 /** |
522 * Returns a link to [member], relative to a type page that may be in a | 522 * Returns a link to [member], relative to a type page that may be in a |
523 * different library than [member]. | 523 * different library than [member]. |
524 */ | 524 */ |
525 String _linkMember(MemberMirror member) { | 525 String _linkMember(MemberMirror member) { |
526 final typeName = member.surroundingDeclaration.simpleName; | 526 final typeName = member.surroundingDeclaration.simpleName; |
527 var memberName = '$typeName.${member.simpleName}'; | 527 var memberName = '$typeName.${member.simpleName}'; |
528 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { | 528 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { |
529 final separator = member.constructorName == '' ? '' : '.'; | 529 final separator = member.constructorName == '' ? '' : '.'; |
530 memberName = 'new $typeName$separator${member.constructorName}'; | 530 memberName = 'new $typeName$separator${member.constructorName}'; |
531 } | 531 } |
532 | 532 |
533 return a(memberUrl(member), memberName); | 533 return a(memberUrl(member), memberName); |
534 } | 534 } |
535 } | 535 } |
OLD | NEW |