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 } else { |
464 // Not a DOM type. | 465 // Not a DOM type. |
465 return null; | 466 return null; |
466 } | 467 } |
467 | 468 |
468 final mdnType = mdn[type.simpleName]; | 469 final mdnType = mdn[typeString]; |
469 if (mdnType == null) return null; | 470 if (mdnType == null) return null; |
470 if (mdnType['skipped'] != null) return null; | 471 if (mdnType['skipped'] != null) return null; |
471 | 472 |
472 // Remember which MDN page we're using so we can attribute it. | 473 // Remember which MDN page we're using so we can attribute it. |
473 mdnUrl = mdnType['srcUrl']; | 474 mdnUrl = mdnType['srcUrl']; |
474 return mdnType['summary']; | 475 return mdnType['summary']; |
475 } | 476 } |
476 | 477 |
477 /** | 478 /** |
478 * Gets the MDN-scraped docs for [member], or `null` if this type isn't | 479 * Gets the MDN-scraped docs for [member], or `null` if this type isn't |
479 * scraped from MDN. | 480 * scraped from MDN. |
480 */ | 481 */ |
481 includeMdnMemberComment(MemberMirror member) { | 482 includeMdnMemberComment(MemberMirror member) { |
482 var library = findLibrary(member); | 483 var library = findLibrary(member); |
| 484 var memberString = ''; |
483 if (library.simpleName == HTML_LIBRARY_NAME) { | 485 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 | 486 // If it's an HTML type, try to map it to a DOM type name so we can find |
485 // the MDN docs. | 487 // the MDN docs. |
486 final domMembers = _diff.htmlToDom[member.qualifiedName]; | 488 final domMembers = _diff.htmlToDom[member.qualifiedName]; |
487 | 489 |
488 // Couldn't find a DOM type. | 490 // Couldn't find a DOM type. |
489 if ((domMembers == null) || (domMembers.length != 1)) return null; | 491 if ((domMembers == null) || (domMembers.length != 1)) return null; |
490 | 492 |
491 // Use the corresponding DOM member when searching MDN. | 493 // Use the corresponding DOM member when searching MDN. |
492 // TODO(rnystrom): Shame there isn't a simpler way to get the one item | 494 // TODO(rnystrom): Shame there isn't a simpler way to get the one item |
493 // out of a singleton Set. | 495 // out of a singleton Set. |
494 member = domMembers.iterator().next(); | 496 memberString = domMembers.iterator().next(); |
495 } else if (library.simpleName != DOM_LIBRARY_NAME) { | 497 } else { |
496 // Not a DOM type. | 498 // Not a DOM type. |
497 return null; | 499 return null; |
498 } | 500 } |
499 | 501 |
500 // Ignore top-level functions. | 502 // Ignore top-level functions. |
501 if (member.isTopLevel) return null; | 503 if (member.isTopLevel) return null; |
502 | 504 |
503 final mdnType = mdn[member.surroundingDeclaration.simpleName]; | |
504 if (mdnType == null) return null; | |
505 var nameToFind = member.simpleName; | |
506 var mdnMember = null; | 505 var mdnMember = null; |
507 for (final candidateMember in mdnType['members']) { | 506 var mdnType = null; |
508 if (candidateMember['name'] == nameToFind) { | 507 var pieces = memberString.split('.'); |
509 mdnMember = candidateMember; | 508 if (pieces.length == 2) { |
510 break; | 509 mdnType = mdn[pieces[0]]; |
| 510 if (mdnType == null) return null; |
| 511 var nameToFind = pieces[1]; |
| 512 for (final candidateMember in mdnType['members']) { |
| 513 if (candidateMember['name'] == nameToFind) { |
| 514 mdnMember = candidateMember; |
| 515 break; |
| 516 } |
511 } | 517 } |
512 } | 518 } |
513 | 519 |
514 if (mdnMember == null) return null; | 520 if (mdnMember == null) return null; |
515 | 521 |
516 // Remember which MDN page we're using so we can attribute it. | 522 // Remember which MDN page we're using so we can attribute it. |
517 mdnUrl = mdnType['srcUrl']; | 523 mdnUrl = mdnType['srcUrl']; |
518 return mdnMember['help']; | 524 return mdnMember['help']; |
519 } | 525 } |
520 | 526 |
521 /** | 527 /** |
522 * Returns a link to [member], relative to a type page that may be in a | 528 * Returns a link to [member], relative to a type page that may be in a |
523 * different library than [member]. | 529 * different library than [member]. |
524 */ | 530 */ |
525 String _linkMember(MemberMirror member) { | 531 String _linkMember(MemberMirror member) { |
526 final typeName = member.surroundingDeclaration.simpleName; | 532 final typeName = member.surroundingDeclaration.simpleName; |
527 var memberName = '$typeName.${member.simpleName}'; | 533 var memberName = '$typeName.${member.simpleName}'; |
528 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { | 534 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { |
529 final separator = member.constructorName == '' ? '' : '.'; | 535 final separator = member.constructorName == '' ? '' : '.'; |
530 memberName = 'new $typeName$separator${member.constructorName}'; | 536 memberName = 'new $typeName$separator${member.constructorName}'; |
531 } | 537 } |
532 | 538 |
533 return a(memberUrl(member), memberName); | 539 return a(memberUrl(member), memberName); |
534 } | 540 } |
535 } | 541 } |
OLD | NEW |