Index: tools/dom/docs/lib/docs.dart |
=================================================================== |
--- tools/dom/docs/lib/docs.dart (revision 32349) |
+++ tools/dom/docs/lib/docs.dart (working copy) |
@@ -1,197 +0,0 @@ |
-// Copyright (c) 2013, 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 library for extracting the documentation from the various HTML libraries |
- * ([dart:html], [dart:svg], [dart:web_audio], [dart:indexed_db]) and saving |
- * those documentation comments to a JSON file. |
- */ |
- |
-library docs; |
- |
-import '../../../../sdk/lib/_internal/dartdoc/lib/src/dart2js_mirrors.dart'; |
-import '../../../../sdk/lib/_internal/compiler/implementation/mirrors/source_mirrors.dart'; |
-import '../../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dart'; |
-import '../../../../sdk/lib/_internal/dartdoc/lib/dartdoc.dart'; |
-import '../../../../sdk/lib/_internal/dartdoc/lib/src/json_serializer.dart'; |
-import '../../../../utils/apidoc/lib/metadata.dart'; |
-import 'dart:async'; |
-import 'dart:io'; |
- |
-/// The various HTML libraries. |
-const List<String> HTML_LIBRARY_NAMES = const ['dart:html', |
- 'dart:indexed_db', |
- 'dart:svg', |
- 'dart:web_audio', |
- 'dart:web_gl', |
- 'dart:web_sql']; |
-/** |
- * Converts the libraries in [HTML_LIBRARY_NAMES] to a json file at [jsonPath] |
- * given the library path at [libUri]. |
- * |
- * The json output looks like: |
- * { |
- * $library_name: { |
- * $interface_name: { |
- * comment: "$comment" |
- * members: { |
- * $member: [ |
- * [$comment1line1, |
- * $comment1line2, |
- * ...], |
- * ... |
- * ], |
- * ... |
- * } |
- * }, |
- * ... |
- * }, |
- * ... |
- * } |
- * |
- * Completes to true if any errors were encountered, false otherwise. |
- */ |
-Future<bool> convert(String libUri, String jsonPath) { |
- var paths = <String>[]; |
- for (var libraryName in HTML_LIBRARY_NAMES) { |
- paths.add(libraryName); |
- } |
- |
- return analyze(paths, libUri, options: ['--preserve-comments']) |
- .then((MirrorSystem mirrors) { |
- var convertedJson = _generateJsonFromLibraries(mirrors); |
- return _exportJsonToFile(convertedJson, jsonPath); |
- }); |
-} |
- |
-Future<bool> _exportJsonToFile(Map convertedJson, String jsonPath) { |
- return new Future.sync(() { |
- final jsonFile = new File(jsonPath); |
- var writeJson = prettySerialize(convertedJson); |
- |
- var outputStream = jsonFile.openWrite(); |
- outputStream.writeln(writeJson); |
- outputStream.close(); |
- return outputStream.done.then((_) => false); |
- }); |
-} |
- |
-Map _generateJsonFromLibraries(MirrorSystem mirrors) { |
- var convertedJson = {}; |
- |
- // Sort the libraries by name (not key). |
- var sortedLibraries = new List<LibraryMirror>.from( |
- mirrors.libraries.values.where( |
- (e) => HTML_LIBRARY_NAMES.indexOf(e.uri.toString()) >= 0)) |
- ..sort((x, y) => |
- x.uri.toString().toUpperCase().compareTo( |
- y.uri.toString().toUpperCase())); |
- |
- for (LibraryMirror libMirror in sortedLibraries) { |
- print('Extracting documentation from ${libMirror.simpleName}.'); |
- |
- var libraryJson = {}; |
- var sortedClasses = _sortAndFilterMirrors( |
- classesOf(libMirror.declarations).toList(), ignoreDocsEditable: true); |
- |
- for (ClassMirror classMirror in sortedClasses) { |
- print(' class: $classMirror'); |
- var classJson = {}; |
- var sortedMembers = _sortAndFilterMirrors( |
- membersOf(classMirror.declarations).toList()); |
- |
- var membersJson = {}; |
- for (var memberMirror in sortedMembers) { |
- print(' member: $memberMirror'); |
- var memberDomName = domNames(memberMirror)[0]; |
- var memberComment = _splitCommentsByNewline( |
- computeUntrimmedCommentAsList(memberMirror)); |
- |
- // Remove interface name from Dom Name. |
- if (memberDomName.indexOf('.') >= 0) { |
- memberDomName = |
- memberDomName.substring(memberDomName.indexOf('.') + 1); |
- } |
- |
- if (!memberComment.isEmpty) { |
- membersJson.putIfAbsent(memberDomName, () => memberComment); |
- } |
- } |
- |
- // Only include the comment if DocsEditable is set. |
- var classComment = _splitCommentsByNewline( |
- computeUntrimmedCommentAsList(classMirror)); |
- if (!classComment.isEmpty && |
- findMetadata(classMirror.metadata, 'DocsEditable') != null) { |
- classJson.putIfAbsent('comment', () => classComment); |
- } |
- if (!membersJson.isEmpty) { |
- classJson.putIfAbsent('members', () => |
- membersJson); |
- } |
- |
- if (!classJson.isEmpty) { |
- libraryJson.putIfAbsent(domNames(classMirror)[0], () => |
- classJson); |
- } |
- } |
- |
- if (!libraryJson.isEmpty) { |
- convertedJson.putIfAbsent(nameOf(libMirror), () => |
- libraryJson); |
- } |
- } |
- |
- return convertedJson; |
-} |
- |
-/// Filter out mirrors that are private, or which are not part of this docs |
-/// process. That is, ones without the DocsEditable annotation. |
-/// If [ignoreDocsEditable] is true, relax the restriction on @DocsEditable(). |
-/// This is to account for classes that are defined in a template, but whose |
-/// members are generated. |
-List<DeclarationMirror> _sortAndFilterMirrors(List<DeclarationMirror> mirrors, |
- {ignoreDocsEditable: false}) { |
- |
- var filteredMirrors = mirrors.where((DeclarationMirror c) => |
- !domNames(c).isEmpty && |
- !displayName(c).startsWith('_') && |
- (!ignoreDocsEditable ? (findMetadata(c.metadata, 'DocsEditable') != null) |
- : true)) |
- .toList(); |
- |
- filteredMirrors.sort((x, y) => |
- domNames(x)[0].toUpperCase().compareTo( |
- domNames(y)[0].toUpperCase())); |
- |
- return filteredMirrors; |
-} |
- |
-List<String> _splitCommentsByNewline(List<String> comments) { |
- var out = []; |
- |
- comments.forEach((c) { |
- out.addAll(c.split(new RegExp('\n'))); |
- }); |
- |
- return out; |
-} |
- |
-/// Given the class mirror, returns the names found or an empty list. |
-List<String> domNames(DeclarationMirror mirror) { |
- var domNameMetadata = findMetadata(mirror.metadata, 'DomName'); |
- |
- if (domNameMetadata != null) { |
- var domNames = <String>[]; |
- var tags = domNameMetadata.getField(#name); |
- for (var s in tags.reflectee.split(',')) { |
- domNames.add(s.trim()); |
- } |
- |
- if (domNames.length == 1 && domNames[0] == 'none') return <String>[]; |
- return domNames; |
- } else { |
- return <String>[]; |
- } |
-} |