nweiz@google.com
f7419664c4
TBR Review URL: http://codereview.chromium.org//8871001 git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart@2204 260f80e4-7a28-3924-810f-c04153c831b5
124 lines
4.3 KiB
Dart
124 lines
4.3 KiB
Dart
// Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file
|
|
// for details. All rights reserved. Use of this source code is governed by a
|
|
// BSD-style license that can be found in the LICENSE file.
|
|
|
|
/**
|
|
* A script to document the HTML library, including annotations on the mapping
|
|
* to and from the DOM library. To use it, from utils/dartdoc, run:
|
|
*
|
|
* $ htmldoc
|
|
*
|
|
* This works just like `dartdoc html`, with the additions of the DOM/HTML
|
|
* mapping documentation.
|
|
*/
|
|
#library('html_doc');
|
|
|
|
#import('html_diff.dart');
|
|
#import('../../../frog/lang.dart');
|
|
#import('../../../frog/file_system_node.dart');
|
|
#import('../../../frog/file_system.dart');
|
|
#import('../../../utils/dartdoc/dartdoc.dart', prefix: 'doc');
|
|
|
|
HtmlDiff _diff;
|
|
|
|
void main() {
|
|
var files = new NodeFileSystem();
|
|
parseOptions('../../frog', [] /* args */, files);
|
|
initializeWorld(files);
|
|
doc.initializeDartDoc();
|
|
HtmlDiff.initialize();
|
|
|
|
_diff = new HtmlDiff();
|
|
_diff.run();
|
|
world.reset();
|
|
|
|
doc.addMethodDocumenter(addMemberDoc);
|
|
doc.addFieldDocumenter(addMemberDoc);
|
|
doc.addTypeDocumenter(addTypeDoc);
|
|
doc.document('html');
|
|
}
|
|
|
|
/**
|
|
* Returns a Markdown-formatted link to [member], relative to a type page that
|
|
* may be in a different library than [member].
|
|
*/
|
|
String _linkMember(Member member) {
|
|
final typeName = member.declaringType.name;
|
|
var memberName = "$typeName.${member.name}";
|
|
if (member.isConstructor || member.isFactory) {
|
|
final separator = member.constructorName == '' ? '' : '.';
|
|
memberName = 'new $typeName$separator${member.constructorName}';
|
|
} else if (member.name.startsWith('get:')) {
|
|
memberName = "$typeName.${member.name.substring(4)}";
|
|
}
|
|
|
|
return "[$memberName](../${doc.memberUrl(member)})";
|
|
}
|
|
|
|
/**
|
|
* Returns a Markdown-formatted link to [type], relative to a type page that
|
|
* may be in a different library than [type].
|
|
*/
|
|
String _linkType(Type type) => "[${type.name}](../${doc.typeUrl(type)})";
|
|
|
|
/**
|
|
* Unify getters and setters of the same property. We only want to print
|
|
* explicit setters if no getter exists.
|
|
*
|
|
* If [members] contains no setters, returns it unmodified.
|
|
*/
|
|
Set<Member> _unifyProperties(Set<Member> members) {
|
|
// Only print setters if the getter doesn't exist.
|
|
return members.filter((m) {
|
|
if (!m.name.startsWith('set:')) return true;
|
|
var getName = m.name.replaceFirst('set:', 'get:');
|
|
return !members.some((maybeGet) => maybeGet.name == getName);
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Returns additional Markdown-formatted documentation for [member], linking it
|
|
* to the corresponding `dart:html` or `dart:dom` [Member](s). If [member] is
|
|
* not in `dart:html` or `dart:dom`, returns no additional documentation.
|
|
*/
|
|
String addMemberDoc(Member member) {
|
|
if (_diff.domToHtml.containsKey(member)) {
|
|
final htmlMemberSet = _unifyProperties(_diff.domToHtml[member]);
|
|
final allSameName = htmlMemberSet.every((m) => _diff.sameName(member, m));
|
|
final phrase = allSameName ? "available as" : "renamed to";
|
|
final htmlMembers = doc.joinWithCommas(map(htmlMemberSet, _linkMember));
|
|
return "_This is $phrase $htmlMembers in the " +
|
|
"[dart:html](../html.html) library._";
|
|
} else if (_diff.htmlToDom.containsKey(member)) {
|
|
final domMemberSet = _unifyProperties(_diff.htmlToDom[member]);
|
|
final allSameName = domMemberSet.every((m) => _diff.sameName(m, member));
|
|
final phrase = allSameName ? "is the same as" : "renames";
|
|
final domMembers = doc.joinWithCommas(map(domMemberSet, _linkMember));
|
|
return "_This $phrase $domMembers in the [dart:dom](../dom.html) " +
|
|
"library._";
|
|
} else {
|
|
return "";
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Returns additional Markdown-formatted documentation for [type], linking it to
|
|
* the corresponding `dart:html` or `dart:dom` [Type](s). If [type] is not in
|
|
* `dart:html` or `dart:dom`, returns no additional documentation.
|
|
*/
|
|
String addTypeDoc(Type type) {
|
|
if (_diff.domTypesToHtml.containsKey(type)) {
|
|
var htmlTypes = doc.joinWithCommas(
|
|
map(_diff.domTypesToHtml[type], _linkType));
|
|
return "_This corresponds to $htmlTypes in the [dart:html](../html.html) " +
|
|
"library._";
|
|
} else if (_diff.htmlTypesToDom.containsKey(type)) {
|
|
var domTypes = doc.joinWithCommas(
|
|
map(_diff.htmlTypesToDom[type], _linkType));
|
|
return "_This corresponds to $domTypes in the [dart:dom](../dom.html) " +
|
|
"library._";
|
|
} else {
|
|
return "";
|
|
}
|
|
}
|