| 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 |