| 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.toFilePath()), | 131 availableLibraries.map((each) => each.uri), |
| 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<String> _listLibraries(List<String> args) { | 192 List<Uri> _listLibraries(List<String> args) { |
| 193 var libraries = new List<String>(); | 193 var libraries = new List<Uri>(); |
| 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(path.absolute(arg)); | 199 libraries.add(new Uri.file(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<String> _listDartFromDir(String args) { | 209 List<Uri> _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(f); | 226 libraries.add(new Uri.file(path.normalize(path.absolute(f)))); |
| 227 logger.info('Added to libraries: $f'); | 227 logger.info('Added to libraries: $f'); |
| 228 } | 228 } |
| 229 } | 229 } |
| 230 }); | 230 }); |
| 231 return libraries.map(path.absolute).map(path.normalize).toList(); | 231 return libraries; |
| 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<String> _listSdk() { | 254 List<Uri> _listSdk() { |
| 255 var sdk = new List<String>(); | 255 var sdk = new List<Uri>(); |
| 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('dart:$name'); | 258 sdk.add(Uri.parse('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<String> libraries, | 267 Future<MirrorSystem> getMirrorSystem(List<Uri> 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<String> libraries, | 289 Future<MirrorSystem> _analyzeLibraries(List<Uri> 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(scheme: 'file', path: appendSlash(libraryRoot)); | 297 Uri libraryUri = new Uri.file(appendSlash(libraryRoot)); |
| 298 Uri packageUri = null; | 298 Uri packageUri = null; |
| 299 if (packageRoot != null) { | 299 if (packageRoot != null) { |
| 300 packageUri = new Uri(scheme: 'file', path: appendSlash(packageRoot)); | 300 packageUri = new Uri.file(appendSlash(packageRoot)); |
| 301 } | 301 } |
| 302 List<Uri> librariesUri = <Uri>[]; | 302 return dart2js.analyze(libraries, libraryUri, packageUri, |
| 303 libraries.forEach((library) { | |
| 304 librariesUri.add(currentDirectory.resolve(library)); | |
| 305 }); | |
| 306 return dart2js.analyze(librariesUri, libraryUri, packageUri, | |
| 307 provider.readStringFromUri, diagnosticHandler, | 303 provider.readStringFromUri, diagnosticHandler, |
| 308 ['--preserve-comments', '--categories=Client,Server']) | 304 ['--preserve-comments', '--categories=Client,Server']) |
| 309 ..catchError((error) { | 305 ..catchError((error) { |
| 310 logger.severe('Error: Failed to create mirror system. '); | 306 logger.severe('Error: Failed to create mirror system. '); |
| 311 // TODO(janicejl): Use the stack trace package when bug is resolved. | 307 // TODO(janicejl): Use the stack trace package when bug is resolved. |
| 312 // Currently, a string is thrown when it fails to create a mirror | 308 // Currently, a string is thrown when it fails to create a mirror |
| 313 // system, and it is not possible to use the stack trace. BUG(#11622) | 309 // system, and it is not possible to use the stack trace. BUG(#11622) |
| 314 // To avoid printing the stack trace. | 310 // To avoid printing the stack trace. |
| 315 exit(1); | 311 exit(1); |
| 316 }); | 312 }); |
| (...skipping 1193 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 1510 /// Remove statics from the map of inherited items before adding them. | 1506 /// Remove statics from the map of inherited items before adding them. |
| 1511 Map _filterStatics(Map items) { | 1507 Map _filterStatics(Map items) { |
| 1512 var result = {}; | 1508 var result = {}; |
| 1513 items.forEach((name, item) { | 1509 items.forEach((name, item) { |
| 1514 if (!item.isStatic) { | 1510 if (!item.isStatic) { |
| 1515 result[name] = item; | 1511 result[name] = item; |
| 1516 } | 1512 } |
| 1517 }); | 1513 }); |
| 1518 return result; | 1514 return result; |
| 1519 } | 1515 } |
| OLD | NEW |