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 221 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
232 } | 232 } |
233 | 233 |
234 class Apidoc extends doc.Dartdoc { | 234 class Apidoc extends doc.Dartdoc { |
235 /** Big ball of JSON containing the scraped MDN documentation. */ | 235 /** Big ball of JSON containing the scraped MDN documentation. */ |
236 final Map mdn; | 236 final Map mdn; |
237 | 237 |
238 final Htmldoc htmldoc; | 238 final Htmldoc htmldoc; |
239 | 239 |
240 static const disqusShortname = 'dartapidocs'; | 240 static const disqusShortname = 'dartapidocs'; |
241 | 241 |
| 242 // A set of type names (TypeMirror.simpleName values) to ignore while |
| 243 // looking up information from MDN data. TODO(eub, jacobr): fix up the MDN |
| 244 // import scripts so they run correctly and generate data that doesn't have |
| 245 // any entries that need to be ignored. |
| 246 static Set<String> _mdnTypeNamesToSkip = null; |
| 247 |
242 /** | 248 /** |
243 * The URL to the page on MDN that content was pulled from for the current | 249 * The URL to the page on MDN that content was pulled from for the current |
244 * type being documented. Will be `null` if the type doesn't use any MDN | 250 * type being documented. Will be `null` if the type doesn't use any MDN |
245 * content. | 251 * content. |
246 */ | 252 */ |
247 String mdnUrl; | 253 String mdnUrl; |
248 | 254 |
249 Apidoc(this.mdn, this.htmldoc, Path outputDir, int mode, | 255 Apidoc(this.mdn, this.htmldoc, Path outputDir, int mode, |
250 bool generateAppCache) { | 256 bool generateAppCache) { |
251 this.outputDir = outputDir; | 257 this.outputDir = outputDir; |
252 this.mode = mode; | 258 this.mode = mode; |
253 this.generateAppCache = generateAppCache; | 259 this.generateAppCache = generateAppCache; |
254 | 260 |
| 261 // Skip bad entries in the checked-in mdn/database.json: |
| 262 // * UnknownElement has a top-level Gecko DOM page in German. |
| 263 if (_mdnTypeNamesToSkip == null) |
| 264 _mdnTypeNamesToSkip = new Set.from(['UnknownElement']); |
| 265 |
255 mainTitle = 'Dart API Reference'; | 266 mainTitle = 'Dart API Reference'; |
256 mainUrl = 'http://dartlang.org'; | 267 mainUrl = 'http://dartlang.org'; |
257 | 268 |
258 final note = 'http://code.google.com/policies.html#restrictions'; | 269 final note = 'http://code.google.com/policies.html#restrictions'; |
259 final cca = 'http://creativecommons.org/licenses/by/3.0/'; | 270 final cca = 'http://creativecommons.org/licenses/by/3.0/'; |
260 final bsd = 'http://code.google.com/google_bsd_license.html'; | 271 final bsd = 'http://code.google.com/google_bsd_license.html'; |
261 final tos = 'http://www.dartlang.org/tos.html'; | 272 final tos = 'http://www.dartlang.org/tos.html'; |
262 final privacy = 'http://www.google.com/intl/en/privacy/privacy-policy.html'; | 273 final privacy = 'http://www.google.com/intl/en/privacy/privacy-policy.html'; |
263 | 274 |
264 footerText = | 275 footerText = |
(...skipping 176 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
441 </p> | 452 </p> |
442 '''); | 453 '''); |
443 } | 454 } |
444 } | 455 } |
445 | 456 |
446 /** | 457 /** |
447 * Gets the MDN-scraped docs for [type], or `null` if this type isn't | 458 * Gets the MDN-scraped docs for [type], or `null` if this type isn't |
448 * scraped from MDN. | 459 * scraped from MDN. |
449 */ | 460 */ |
450 includeMdnTypeComment(TypeMirror type) { | 461 includeMdnTypeComment(TypeMirror type) { |
| 462 if (_mdnTypeNamesToSkip.contains(type.simpleName)) { |
| 463 print('Skipping MDN type ${type.simpleName}'); |
| 464 return null; |
| 465 } |
| 466 |
451 var typeString = ''; | 467 var typeString = ''; |
452 if (type.library.simpleName == HTML_LIBRARY_NAME) { | 468 if (type.library.simpleName == HTML_LIBRARY_NAME) { |
453 // If it's an HTML type, try to map it to a base DOM type so we can find | 469 // If it's an HTML type, try to map it to a base DOM type so we can find |
454 // the MDN docs. | 470 // the MDN docs. |
455 final domTypes = _diff.htmlTypesToDom[type.qualifiedName]; | 471 final domTypes = _diff.htmlTypesToDom[type.qualifiedName]; |
456 | 472 |
457 // Couldn't find a DOM type. | 473 // Couldn't find a DOM type. |
458 if ((domTypes == null) || (domTypes.length != 1)) return null; | 474 if ((domTypes == null) || (domTypes.length != 1)) return null; |
459 | 475 |
460 // Use the corresponding DOM type when searching MDN. | 476 // Use the corresponding DOM type when searching MDN. |
(...skipping 71 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
532 final typeName = member.surroundingDeclaration.simpleName; | 548 final typeName = member.surroundingDeclaration.simpleName; |
533 var memberName = '$typeName.${member.simpleName}'; | 549 var memberName = '$typeName.${member.simpleName}'; |
534 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { | 550 if (member is MethodMirror && (member.isConstructor || member.isFactory)) { |
535 final separator = member.constructorName == '' ? '' : '.'; | 551 final separator = member.constructorName == '' ? '' : '.'; |
536 memberName = 'new $typeName$separator${member.constructorName}'; | 552 memberName = 'new $typeName$separator${member.constructorName}'; |
537 } | 553 } |
538 | 554 |
539 return a(memberUrl(member), memberName); | 555 return a(memberUrl(member), memberName); |
540 } | 556 } |
541 } | 557 } |
OLD | NEW |