| 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 |