Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(356)

Side by Side Diff: tools/dom/docs/lib/docs.dart

Issue 156903004: Remove more tests which depend on dartdoc, which has been deleted. (Closed) Base URL: http://dart.googlecode.com/svn/branches/bleeding_edge/dart/
Patch Set: Created 6 years, 10 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
« no previous file with comments | « tools/dom/docs/docs.status ('k') | tools/dom/docs/test/docs_test.dart » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(Empty)
1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file
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.
4
5 /**
6 * A library for extracting the documentation from the various HTML libraries
7 * ([dart:html], [dart:svg], [dart:web_audio], [dart:indexed_db]) and saving
8 * those documentation comments to a JSON file.
9 */
10
11 library docs;
12
13 import '../../../../sdk/lib/_internal/dartdoc/lib/src/dart2js_mirrors.dart';
14 import '../../../../sdk/lib/_internal/compiler/implementation/mirrors/source_mir rors.dart';
15 import '../../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_ut il.dart';
16 import '../../../../sdk/lib/_internal/dartdoc/lib/dartdoc.dart';
17 import '../../../../sdk/lib/_internal/dartdoc/lib/src/json_serializer.dart';
18 import '../../../../utils/apidoc/lib/metadata.dart';
19 import 'dart:async';
20 import 'dart:io';
21
22 /// The various HTML libraries.
23 const List<String> HTML_LIBRARY_NAMES = const ['dart:html',
24 'dart:indexed_db',
25 'dart:svg',
26 'dart:web_audio',
27 'dart:web_gl',
28 'dart:web_sql'];
29 /**
30 * Converts the libraries in [HTML_LIBRARY_NAMES] to a json file at [jsonPath]
31 * given the library path at [libUri].
32 *
33 * The json output looks like:
34 * {
35 * $library_name: {
36 * $interface_name: {
37 * comment: "$comment"
38 * members: {
39 * $member: [
40 * [$comment1line1,
41 * $comment1line2,
42 * ...],
43 * ...
44 * ],
45 * ...
46 * }
47 * },
48 * ...
49 * },
50 * ...
51 * }
52 *
53 * Completes to true if any errors were encountered, false otherwise.
54 */
55 Future<bool> convert(String libUri, String jsonPath) {
56 var paths = <String>[];
57 for (var libraryName in HTML_LIBRARY_NAMES) {
58 paths.add(libraryName);
59 }
60
61 return analyze(paths, libUri, options: ['--preserve-comments'])
62 .then((MirrorSystem mirrors) {
63 var convertedJson = _generateJsonFromLibraries(mirrors);
64 return _exportJsonToFile(convertedJson, jsonPath);
65 });
66 }
67
68 Future<bool> _exportJsonToFile(Map convertedJson, String jsonPath) {
69 return new Future.sync(() {
70 final jsonFile = new File(jsonPath);
71 var writeJson = prettySerialize(convertedJson);
72
73 var outputStream = jsonFile.openWrite();
74 outputStream.writeln(writeJson);
75 outputStream.close();
76 return outputStream.done.then((_) => false);
77 });
78 }
79
80 Map _generateJsonFromLibraries(MirrorSystem mirrors) {
81 var convertedJson = {};
82
83 // Sort the libraries by name (not key).
84 var sortedLibraries = new List<LibraryMirror>.from(
85 mirrors.libraries.values.where(
86 (e) => HTML_LIBRARY_NAMES.indexOf(e.uri.toString()) >= 0))
87 ..sort((x, y) =>
88 x.uri.toString().toUpperCase().compareTo(
89 y.uri.toString().toUpperCase()));
90
91 for (LibraryMirror libMirror in sortedLibraries) {
92 print('Extracting documentation from ${libMirror.simpleName}.');
93
94 var libraryJson = {};
95 var sortedClasses = _sortAndFilterMirrors(
96 classesOf(libMirror.declarations).toList(), ignoreDocsEditable: true);
97
98 for (ClassMirror classMirror in sortedClasses) {
99 print(' class: $classMirror');
100 var classJson = {};
101 var sortedMembers = _sortAndFilterMirrors(
102 membersOf(classMirror.declarations).toList());
103
104 var membersJson = {};
105 for (var memberMirror in sortedMembers) {
106 print(' member: $memberMirror');
107 var memberDomName = domNames(memberMirror)[0];
108 var memberComment = _splitCommentsByNewline(
109 computeUntrimmedCommentAsList(memberMirror));
110
111 // Remove interface name from Dom Name.
112 if (memberDomName.indexOf('.') >= 0) {
113 memberDomName =
114 memberDomName.substring(memberDomName.indexOf('.') + 1);
115 }
116
117 if (!memberComment.isEmpty) {
118 membersJson.putIfAbsent(memberDomName, () => memberComment);
119 }
120 }
121
122 // Only include the comment if DocsEditable is set.
123 var classComment = _splitCommentsByNewline(
124 computeUntrimmedCommentAsList(classMirror));
125 if (!classComment.isEmpty &&
126 findMetadata(classMirror.metadata, 'DocsEditable') != null) {
127 classJson.putIfAbsent('comment', () => classComment);
128 }
129 if (!membersJson.isEmpty) {
130 classJson.putIfAbsent('members', () =>
131 membersJson);
132 }
133
134 if (!classJson.isEmpty) {
135 libraryJson.putIfAbsent(domNames(classMirror)[0], () =>
136 classJson);
137 }
138 }
139
140 if (!libraryJson.isEmpty) {
141 convertedJson.putIfAbsent(nameOf(libMirror), () =>
142 libraryJson);
143 }
144 }
145
146 return convertedJson;
147 }
148
149 /// Filter out mirrors that are private, or which are not part of this docs
150 /// process. That is, ones without the DocsEditable annotation.
151 /// If [ignoreDocsEditable] is true, relax the restriction on @DocsEditable().
152 /// This is to account for classes that are defined in a template, but whose
153 /// members are generated.
154 List<DeclarationMirror> _sortAndFilterMirrors(List<DeclarationMirror> mirrors,
155 {ignoreDocsEditable: false}) {
156
157 var filteredMirrors = mirrors.where((DeclarationMirror c) =>
158 !domNames(c).isEmpty &&
159 !displayName(c).startsWith('_') &&
160 (!ignoreDocsEditable ? (findMetadata(c.metadata, 'DocsEditable') != null)
161 : true))
162 .toList();
163
164 filteredMirrors.sort((x, y) =>
165 domNames(x)[0].toUpperCase().compareTo(
166 domNames(y)[0].toUpperCase()));
167
168 return filteredMirrors;
169 }
170
171 List<String> _splitCommentsByNewline(List<String> comments) {
172 var out = [];
173
174 comments.forEach((c) {
175 out.addAll(c.split(new RegExp('\n')));
176 });
177
178 return out;
179 }
180
181 /// Given the class mirror, returns the names found or an empty list.
182 List<String> domNames(DeclarationMirror mirror) {
183 var domNameMetadata = findMetadata(mirror.metadata, 'DomName');
184
185 if (domNameMetadata != null) {
186 var domNames = <String>[];
187 var tags = domNameMetadata.getField(#name);
188 for (var s in tags.reflectee.split(',')) {
189 domNames.add(s.trim());
190 }
191
192 if (domNames.length == 1 && domNames[0] == 'none') return <String>[];
193 return domNames;
194 } else {
195 return <String>[];
196 }
197 }
OLDNEW
« no previous file with comments | « tools/dom/docs/docs.status ('k') | tools/dom/docs/test/docs_test.dart » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698