OLD | NEW |
1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | 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 | 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 /// **docgen** is a tool for creating machine readable representations of Dart | 5 /// **docgen** is a tool for creating machine readable representations of Dart |
6 /// code metadata, including: classes, members, comments and annotations. | 6 /// code metadata, including: classes, members, comments and annotations. |
7 /// | 7 /// |
8 /// docgen is run on a `.dart` file or a directory containing `.dart` files. | 8 /// docgen is run on a `.dart` file or a directory containing `.dart` files. |
9 /// | 9 /// |
10 /// $ dart docgen.dart [OPTIONS] [FILE/DIR] | 10 /// $ dart docgen.dart [OPTIONS] [FILE/DIR] |
(...skipping 110 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
121 if (mirrorSystem.libraries.isEmpty) { | 121 if (mirrorSystem.libraries.isEmpty) { |
122 throw new StateError('No library mirrors were created.'); | 122 throw new StateError('No library mirrors were created.'); |
123 } | 123 } |
124 var availableLibraries = mirrorSystem.libraries.values.where( | 124 var availableLibraries = mirrorSystem.libraries.values.where( |
125 (each) => each.uri.scheme == 'file'); | 125 (each) => each.uri.scheme == 'file'); |
126 _sdkLibraries = mirrorSystem.libraries.values.where( | 126 _sdkLibraries = mirrorSystem.libraries.values.where( |
127 (each) => each.uri.scheme == 'dart'); | 127 (each) => each.uri.scheme == 'dart'); |
128 _coreLibrary = _sdkLibraries.singleWhere((lib) => | 128 _coreLibrary = _sdkLibraries.singleWhere((lib) => |
129 lib.uri.toString().startsWith('dart:core')); | 129 lib.uri.toString().startsWith('dart:core')); |
130 var availableLibrariesByPath = new Map.fromIterables( | 130 var availableLibrariesByPath = new Map.fromIterables( |
131 availableLibraries.map((each) => each.uri), | 131 availableLibraries.map((each) => each.uri.toFilePath()), |
132 availableLibraries); | 132 availableLibraries); |
133 var librariesToDocument = requestedLibraries.map( | 133 var librariesToDocument = requestedLibraries.map( |
134 (each) => availableLibrariesByPath.putIfAbsent(each, | 134 (each) => availableLibrariesByPath.putIfAbsent(each, |
135 () => throw "Missing library $each")).toList(); | 135 () => throw "Missing library $each")).toList(); |
136 librariesToDocument.addAll((includeSdk || parseSdk) ? _sdkLibraries : []); | 136 librariesToDocument.addAll((includeSdk || parseSdk) ? _sdkLibraries : []); |
137 librariesToDocument.removeWhere((x) => _excluded.contains(x.simpleName)); | 137 librariesToDocument.removeWhere((x) => _excluded.contains(x.simpleName)); |
138 _documentLibraries(librariesToDocument, includeSdk: includeSdk, | 138 _documentLibraries(librariesToDocument, includeSdk: includeSdk, |
139 outputToYaml: outputToYaml, append: append, parseSdk: parseSdk, | 139 outputToYaml: outputToYaml, append: append, parseSdk: parseSdk, |
140 introduction: introduction); | 140 introduction: introduction); |
141 return true; | 141 return true; |
(...skipping 40 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
182 // If there are multiples, pick the shortest name. | 182 // If there are multiples, pick the shortest name. |
183 readmes.sort((a, b) => a.length.compareTo(b.length)); | 183 readmes.sort((a, b) => a.length.compareTo(b.length)); |
184 var readme = readmes.first; | 184 var readme = readmes.first; |
185 var linkResolver = (name) => fixReference(name, null, null, null); | 185 var linkResolver = (name) => fixReference(name, null, null, null); |
186 var contents = markdown.markdownToHtml(readme | 186 var contents = markdown.markdownToHtml(readme |
187 .readAsStringSync(), linkResolver: linkResolver, | 187 .readAsStringSync(), linkResolver: linkResolver, |
188 inlineSyntaxes: markdownSyntaxes); | 188 inlineSyntaxes: markdownSyntaxes); |
189 return contents; | 189 return contents; |
190 } | 190 } |
191 | 191 |
192 List<Uri> _listLibraries(List<String> args) { | 192 List<String> _listLibraries(List<String> args) { |
193 var libraries = new List<Uri>(); | 193 var libraries = new List<String>(); |
194 for (var arg in args) { | 194 for (var arg in args) { |
195 var type = FileSystemEntity.typeSync(arg); | 195 var type = FileSystemEntity.typeSync(arg); |
196 | 196 |
197 if (type == FileSystemEntityType.FILE) { | 197 if (type == FileSystemEntityType.FILE) { |
198 if (arg.endsWith('.dart')) { | 198 if (arg.endsWith('.dart')) { |
199 libraries.add(new Uri.file(path.absolute(arg))); | 199 libraries.add(path.absolute(arg)); |
200 logger.info('Added to libraries: ${libraries.last}'); | 200 logger.info('Added to libraries: ${libraries.last}'); |
201 } | 201 } |
202 } else { | 202 } else { |
203 libraries.addAll(_listDartFromDir(arg)); | 203 libraries.addAll(_listDartFromDir(arg)); |
204 } | 204 } |
205 } | 205 } |
206 return libraries; | 206 return libraries; |
207 } | 207 } |
208 | 208 |
209 List<Uri> _listDartFromDir(String args) { | 209 List<String> _listDartFromDir(String args) { |
210 var libraries = []; | 210 var libraries = []; |
211 // To avoid anaylzing package files twice, only files with paths not | 211 // To avoid anaylzing package files twice, only files with paths not |
212 // containing '/packages' will be added. The only exception is if the file to | 212 // containing '/packages' will be added. The only exception is if the file to |
213 // analyze already has a '/package' in its path. | 213 // analyze already has a '/package' in its path. |
214 var files = listDir(args, recursive: true).where((f) => f.endsWith('.dart') && | 214 var files = listDir(args, recursive: true).where((f) => f.endsWith('.dart') && |
215 (!f.contains('${path.separator}packages') || | 215 (!f.contains('${path.separator}packages') || |
216 args.contains('${path.separator}packages'))).toList(); | 216 args.contains('${path.separator}packages'))).toList(); |
217 | 217 |
218 files.forEach((String f) { | 218 files.forEach((String f) { |
219 // Only include libraries at the top level of "lib" | 219 // Only include libraries at the top level of "lib" |
220 if (path.basename(path.dirname(f)) == 'lib') { | 220 if (path.basename(path.dirname(f)) == 'lib') { |
221 // Only add the file if it does not contain 'part of' | 221 // Only add the file if it does not contain 'part of' |
222 // TODO(janicejl): Remove when Issue(12406) is resolved. | 222 // TODO(janicejl): Remove when Issue(12406) is resolved. |
223 var contents = new File(f).readAsStringSync(); | 223 var contents = new File(f).readAsStringSync(); |
224 if (!(contents.contains(new RegExp('\npart of ')) || | 224 if (!(contents.contains(new RegExp('\npart of ')) || |
225 contents.startsWith(new RegExp('part of ')))) { | 225 contents.startsWith(new RegExp('part of ')))) { |
226 libraries.add(new Uri.file(path.normalize(path.absolute(f)))); | 226 libraries.add(f); |
227 logger.info('Added to libraries: $f'); | 227 logger.info('Added to libraries: $f'); |
228 } | 228 } |
229 } | 229 } |
230 }); | 230 }); |
231 return libraries; | 231 return libraries.map(path.absolute).map(path.normalize).toList(); |
232 } | 232 } |
233 | 233 |
234 String _findPackageRoot(String directory) { | 234 String _findPackageRoot(String directory) { |
235 var files = listDir(directory, recursive: true); | 235 var files = listDir(directory, recursive: true); |
236 // Return '' means that there was no pubspec.yaml and therefor no packageRoot. | 236 // Return '' means that there was no pubspec.yaml and therefor no packageRoot. |
237 String packageRoot = files.firstWhere((f) => | 237 String packageRoot = files.firstWhere((f) => |
238 f.endsWith('${path.separator}pubspec.yaml'), orElse: () => ''); | 238 f.endsWith('${path.separator}pubspec.yaml'), orElse: () => ''); |
239 if (packageRoot != '') { | 239 if (packageRoot != '') { |
240 packageRoot = path.join(path.dirname(packageRoot), 'packages'); | 240 packageRoot = path.join(path.dirname(packageRoot), 'packages'); |
241 } | 241 } |
242 return packageRoot; | 242 return packageRoot; |
243 } | 243 } |
244 | 244 |
245 /// Read a pubspec and return the library name. | 245 /// Read a pubspec and return the library name. |
246 String _packageName(String pubspecName) { | 246 String _packageName(String pubspecName) { |
247 File pubspec = new File(pubspecName); | 247 File pubspec = new File(pubspecName); |
248 if (!pubspec.existsSync()) return ''; | 248 if (!pubspec.existsSync()) return ''; |
249 var contents = pubspec.readAsStringSync(); | 249 var contents = pubspec.readAsStringSync(); |
250 var spec = loadYaml(contents); | 250 var spec = loadYaml(contents); |
251 return spec["name"]; | 251 return spec["name"]; |
252 } | 252 } |
253 | 253 |
254 List<Uri> _listSdk() { | 254 List<String> _listSdk() { |
255 var sdk = new List<Uri>(); | 255 var sdk = new List<String>(); |
256 LIBRARIES.forEach((String name, LibraryInfo info) { | 256 LIBRARIES.forEach((String name, LibraryInfo info) { |
257 if (info.documented) { | 257 if (info.documented) { |
258 sdk.add(Uri.parse('dart:$name')); | 258 sdk.add('dart:$name'); |
259 logger.info('Add to SDK: ${sdk.last}'); | 259 logger.info('Add to SDK: ${sdk.last}'); |
260 } | 260 } |
261 }); | 261 }); |
262 return sdk; | 262 return sdk; |
263 } | 263 } |
264 | 264 |
265 /// Analyzes set of libraries by getting a mirror system and triggers the | 265 /// Analyzes set of libraries by getting a mirror system and triggers the |
266 /// documentation of the libraries. | 266 /// documentation of the libraries. |
267 Future<MirrorSystem> getMirrorSystem(List<Uri> libraries, | 267 Future<MirrorSystem> getMirrorSystem(List<String> libraries, |
268 {String packageRoot, bool parseSdk: false}) { | 268 {String packageRoot, bool parseSdk: false}) { |
269 if (libraries.isEmpty) throw new StateError('No Libraries.'); | 269 if (libraries.isEmpty) throw new StateError('No Libraries.'); |
270 // Finds the root of SDK library based off the location of docgen. | 270 // Finds the root of SDK library based off the location of docgen. |
271 | 271 |
272 var root = findRootDirectory(); | 272 var root = findRootDirectory(); |
273 var sdkRoot = path.normalize(path.absolute(path.join(root, 'sdk'))); | 273 var sdkRoot = path.normalize(path.absolute(path.join(root, 'sdk'))); |
274 logger.info('SDK Root: ${sdkRoot}'); | 274 logger.info('SDK Root: ${sdkRoot}'); |
275 return _analyzeLibraries(libraries, sdkRoot, packageRoot: packageRoot); | 275 return _analyzeLibraries(libraries, sdkRoot, packageRoot: packageRoot); |
276 } | 276 } |
277 | 277 |
278 String findRootDirectory() { | 278 String findRootDirectory() { |
279 var scriptDir = path.absolute(path.dirname(Platform.script.toFilePath())); | 279 var scriptDir = path.absolute(path.dirname(Platform.script.toFilePath())); |
280 var root = scriptDir; | 280 var root = scriptDir; |
281 while(path.basename(root) != 'dart') { | 281 while(path.basename(root) != 'dart') { |
282 root = path.dirname(root); | 282 root = path.dirname(root); |
283 } | 283 } |
284 return root; | 284 return root; |
285 } | 285 } |
286 | 286 |
287 /// Analyzes set of libraries and provides a mirror system which can be used | 287 /// Analyzes set of libraries and provides a mirror system which can be used |
288 /// for static inspection of the source code. | 288 /// for static inspection of the source code. |
289 Future<MirrorSystem> _analyzeLibraries(List<Uri> libraries, | 289 Future<MirrorSystem> _analyzeLibraries(List<String> libraries, |
290 String libraryRoot, {String packageRoot}) { | 290 String libraryRoot, {String packageRoot}) { |
291 SourceFileProvider provider = new CompilerSourceFileProvider(); | 291 SourceFileProvider provider = new CompilerSourceFileProvider(); |
292 api.DiagnosticHandler diagnosticHandler = | 292 api.DiagnosticHandler diagnosticHandler = |
293 (new FormattingDiagnosticHandler(provider) | 293 (new FormattingDiagnosticHandler(provider) |
294 ..showHints = false | 294 ..showHints = false |
295 ..showWarnings = false) | 295 ..showWarnings = false) |
296 .diagnosticHandler; | 296 .diagnosticHandler; |
297 Uri libraryUri = new Uri.file(appendSlash(libraryRoot)); | 297 Uri libraryUri = new Uri(scheme: 'file', path: appendSlash(libraryRoot)); |
298 Uri packageUri = null; | 298 Uri packageUri = null; |
299 if (packageRoot != null) { | 299 if (packageRoot != null) { |
300 packageUri = new Uri.file(appendSlash(packageRoot)); | 300 packageUri = new Uri(scheme: 'file', path: appendSlash(packageRoot)); |
301 } | 301 } |
302 return dart2js.analyze(libraries, libraryUri, packageUri, | 302 List<Uri> librariesUri = <Uri>[]; |
| 303 libraries.forEach((library) { |
| 304 librariesUri.add(currentDirectory.resolve(library)); |
| 305 }); |
| 306 return dart2js.analyze(librariesUri, libraryUri, packageUri, |
303 provider.readStringFromUri, diagnosticHandler, | 307 provider.readStringFromUri, diagnosticHandler, |
304 ['--preserve-comments', '--categories=Client,Server']) | 308 ['--preserve-comments', '--categories=Client,Server']) |
305 ..catchError((error) { | 309 ..catchError((error) { |
306 logger.severe('Error: Failed to create mirror system. '); | 310 logger.severe('Error: Failed to create mirror system. '); |
307 // TODO(janicejl): Use the stack trace package when bug is resolved. | 311 // TODO(janicejl): Use the stack trace package when bug is resolved. |
308 // Currently, a string is thrown when it fails to create a mirror | 312 // Currently, a string is thrown when it fails to create a mirror |
309 // system, and it is not possible to use the stack trace. BUG(#11622) | 313 // system, and it is not possible to use the stack trace. BUG(#11622) |
310 // To avoid printing the stack trace. | 314 // To avoid printing the stack trace. |
311 exit(1); | 315 exit(1); |
312 }); | 316 }); |
(...skipping 1193 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1506 /// Remove statics from the map of inherited items before adding them. | 1510 /// Remove statics from the map of inherited items before adding them. |
1507 Map _filterStatics(Map items) { | 1511 Map _filterStatics(Map items) { |
1508 var result = {}; | 1512 var result = {}; |
1509 items.forEach((name, item) { | 1513 items.forEach((name, item) { |
1510 if (!item.isStatic) { | 1514 if (!item.isStatic) { |
1511 result[name] = item; | 1515 result[name] = item; |
1512 } | 1516 } |
1513 }); | 1517 }); |
1514 return result; | 1518 return result; |
1515 } | 1519 } |
OLD | NEW |