| 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 /** | 5 /** |
| 6 * **docgen** is a tool for creating machine readable representations of Dart | 6 * **docgen** is a tool for creating machine readable representations of Dart |
| 7 * code metadata, including: classes, members, comments and annotations. | 7 * code metadata, including: classes, members, comments and annotations. |
| 8 * | 8 * |
| 9 * docgen is run on a `.dart` file or a directory containing `.dart` files. | 9 * docgen is run on a `.dart` file or a directory containing `.dart` files. |
| 10 * | 10 * |
| (...skipping 65 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 76 if (FileSystemEntity.typeSync(files.first) | 76 if (FileSystemEntity.typeSync(files.first) |
| 77 == FileSystemEntityType.DIRECTORY) { | 77 == FileSystemEntityType.DIRECTORY) { |
| 78 packageRoot = _findPackageRoot(files.first); | 78 packageRoot = _findPackageRoot(files.first); |
| 79 } | 79 } |
| 80 } | 80 } |
| 81 logger.info('Package Root: ${packageRoot}'); | 81 logger.info('Package Root: ${packageRoot}'); |
| 82 | 82 |
| 83 linkResolver = (name) => | 83 linkResolver = (name) => |
| 84 fixReference(name, _currentLibrary, _currentClass, _currentMember); | 84 fixReference(name, _currentLibrary, _currentClass, _currentMember); |
| 85 | 85 |
| 86 return getMirrorSystem(files, packageRoot, parseSdk: parseSdk) | 86 return getMirrorSystem(files, packageRoot: packageRoot, parseSdk: parseSdk) |
| 87 .then((MirrorSystem mirrorSystem) { | 87 .then((MirrorSystem mirrorSystem) { |
| 88 if (mirrorSystem.libraries.isEmpty) { | 88 if (mirrorSystem.libraries.isEmpty) { |
| 89 throw new StateError('No library mirrors were created.'); | 89 throw new StateError('No library mirrors were created.'); |
| 90 } | 90 } |
| 91 _documentLibraries(mirrorSystem.libraries.values, | 91 _documentLibraries(mirrorSystem.libraries.values, |
| 92 includeSdk: includeSdk, includePrivate: includePrivate, | 92 includeSdk: includeSdk, includePrivate: includePrivate, |
| 93 outputToYaml: outputToYaml); | 93 outputToYaml: outputToYaml); |
| 94 | 94 |
| 95 return true; | 95 return true; |
| 96 }); | 96 }); |
| (...skipping 15 matching lines...) Expand all Loading... |
| 112 } | 112 } |
| 113 return libraries; | 113 return libraries; |
| 114 } | 114 } |
| 115 | 115 |
| 116 List<String> _listDartFromDir(String args) { | 116 List<String> _listDartFromDir(String args) { |
| 117 var files = listDir(args, recursive: true); | 117 var files = listDir(args, recursive: true); |
| 118 // To avoid anaylzing package files twice, only files with paths not | 118 // To avoid anaylzing package files twice, only files with paths not |
| 119 // containing '/packages' will be added. The only exception is if the file to | 119 // containing '/packages' will be added. The only exception is if the file to |
| 120 // analyze already has a '/package' in its path. | 120 // analyze already has a '/package' in its path. |
| 121 return files.where((f) => f.endsWith('.dart') && | 121 return files.where((f) => f.endsWith('.dart') && |
| 122 (!f.contains('/packages') || args.contains('/packages'))).toList() | 122 (!f.contains('${path.separator}packages') || |
| 123 args.contains('${path.separator}packages'))).toList() |
| 123 ..forEach((lib) => logger.info('Added to libraries: $lib')); | 124 ..forEach((lib) => logger.info('Added to libraries: $lib')); |
| 124 } | 125 } |
| 125 | 126 |
| 126 String _findPackageRoot(String directory) { | 127 String _findPackageRoot(String directory) { |
| 127 var files = listDir(directory, recursive: true); | 128 var files = listDir(directory, recursive: true); |
| 128 // Return '' means that there was no pubspec.yaml and therefor no packageRoot. | 129 // Return '' means that there was no pubspec.yaml and therefor no packageRoot. |
| 129 String packageRoot = files.firstWhere((f) => | 130 String packageRoot = files.firstWhere((f) => |
| 130 f.endsWith('/pubspec.yaml'), orElse: () => ''); | 131 f.endsWith('${path.separator}pubspec.yaml'), orElse: () => ''); |
| 131 if (packageRoot != '') { | 132 if (packageRoot != '') { |
| 132 packageRoot = path.dirname(packageRoot) + '/packages'; | 133 packageRoot = path.join(path.dirname(packageRoot), 'packages'); |
| 133 } | 134 } |
| 134 return packageRoot; | 135 return packageRoot; |
| 135 } | 136 } |
| 136 | 137 |
| 137 List<String> _listSdk() { | 138 List<String> _listSdk() { |
| 138 var sdk = new List<String>(); | 139 var sdk = new List<String>(); |
| 139 LIBRARIES.forEach((String name, LibraryInfo info) { | 140 LIBRARIES.forEach((String name, LibraryInfo info) { |
| 140 if (info.documented) { | 141 if (info.documented) { |
| 141 sdk.add('dart:$name'); | 142 sdk.add('dart:$name'); |
| 142 logger.info('Add to SDK: ${sdk.last}'); | 143 logger.info('Add to SDK: ${sdk.last}'); |
| 143 } | 144 } |
| 144 }); | 145 }); |
| 145 return sdk; | 146 return sdk; |
| 146 } | 147 } |
| 147 | 148 |
| 148 /** | 149 /** |
| 149 * Analyzes set of libraries by getting a mirror system and triggers the | 150 * Analyzes set of libraries by getting a mirror system and triggers the |
| 150 * documentation of the libraries. | 151 * documentation of the libraries. |
| 151 */ | 152 */ |
| 152 Future<MirrorSystem> getMirrorSystem(List<String> args, String packageRoot, | 153 Future<MirrorSystem> getMirrorSystem(List<String> args, {String packageRoot, |
| 153 {bool parseSdk:false}) { | 154 bool parseSdk:false}) { |
| 154 var libraries = !parseSdk ? _listLibraries(args) : _listSdk(); | 155 var libraries = !parseSdk ? _listLibraries(args) : _listSdk(); |
| 155 if (libraries.isEmpty) throw new StateError('No Libraries.'); | 156 if (libraries.isEmpty) throw new StateError('No Libraries.'); |
| 156 // DART_SDK should be set to the root of the SDK library. | 157 // DART_SDK should be set to the root of the SDK library. |
| 157 var sdkRoot = Platform.environment['DART_SDK']; | 158 var sdkRoot = Platform.environment['DART_SDK']; |
| 158 if (sdkRoot != null) { | 159 if (sdkRoot != null) { |
| 159 logger.info('Using DART_SDK to find SDK at $sdkRoot'); | 160 logger.info('Using DART_SDK to find SDK at $sdkRoot'); |
| 160 } else { | 161 } else { |
| 161 // If DART_SDK is not defined in the environment, | 162 // If DART_SDK is not defined in the environment, |
| 162 // assuming the dart executable is from the Dart SDK folder inside bin. | 163 // assuming the dart executable is from the Dart SDK folder inside bin. |
| 163 sdkRoot = path.dirname(path.dirname(new Options().executable)); | 164 sdkRoot = path.join(path.dirname(path.dirname(path.dirname(path.dirname( |
| 165 path.absolute(new Options().script))))), 'sdk'); |
| 164 logger.info('SDK Root: ${sdkRoot}'); | 166 logger.info('SDK Root: ${sdkRoot}'); |
| 165 } | 167 } |
| 166 | |
| 167 return _analyzeLibraries(libraries, sdkRoot, packageRoot: packageRoot); | 168 return _analyzeLibraries(libraries, sdkRoot, packageRoot: packageRoot); |
| 168 } | 169 } |
| 169 | 170 |
| 170 // TODO(janicejl): Should make docgen fail gracefully, or output a friendly | 171 // TODO(janicejl): Should make docgen fail gracefully, or output a friendly |
| 171 // error message letting them know why it is failing to create a mirror system. | 172 // error message letting them know why it is failing to create a mirror system. |
| 172 // If there is conflicting library names, should modify it with a hash at the | 173 // If there is conflicting library names, should modify it with a hash at the |
| 173 // end of it's library name. | 174 // end of it's library name. |
| 174 /** | 175 /** |
| 175 * Analyzes set of libraries and provides a mirror system which can be used | 176 * Analyzes set of libraries and provides a mirror system which can be used |
| 176 * for static inspection of the source code. | 177 * for static inspection of the source code. |
| 177 */ | 178 */ |
| 178 Future<MirrorSystem> _analyzeLibraries(List<String> libraries, | 179 Future<MirrorSystem> _analyzeLibraries(List<String> libraries, |
| 179 String libraryRoot, {String packageRoot}) { | 180 String libraryRoot, {String packageRoot}) { |
| 180 SourceFileProvider provider = new SourceFileProvider(); | 181 SourceFileProvider provider = new SourceFileProvider(); |
| 181 api.DiagnosticHandler diagnosticHandler = | 182 api.DiagnosticHandler diagnosticHandler = |
| 182 new FormattingDiagnosticHandler(provider).diagnosticHandler; | 183 new FormattingDiagnosticHandler(provider).diagnosticHandler; |
| 183 Uri libraryUri = currentDirectory.resolve(appendSlash('$libraryRoot')); | 184 Uri libraryUri = new Uri(scheme: 'file', path: appendSlash(libraryRoot)); |
| 184 Uri packageUri = null; | 185 Uri packageUri = null; |
| 185 if (packageRoot != null) { | 186 if (packageRoot != null) { |
| 186 packageUri = currentDirectory.resolve(appendSlash('$packageRoot')); | 187 packageUri = new Uri(scheme: 'file', path: appendSlash(packageRoot)); |
| 187 } | 188 } |
| 188 List<Uri> librariesUri = <Uri>[]; | 189 List<Uri> librariesUri = <Uri>[]; |
| 189 libraries.forEach((library) { | 190 libraries.forEach((library) { |
| 190 librariesUri.add(currentDirectory.resolve(library)); | 191 librariesUri.add(currentDirectory.resolve(library)); |
| 191 }); | 192 }); |
| 192 return dart2js.analyze(librariesUri, libraryUri, packageUri, | 193 return dart2js.analyze(librariesUri, libraryUri, packageUri, |
| 193 provider.readStringFromUri, diagnosticHandler, | 194 provider.readStringFromUri, diagnosticHandler, |
| 194 ['--preserve-comments', '--categories=Client,Server']) | 195 ['--preserve-comments', '--categories=Client,Server']) |
| 195 ..catchError((error) { | 196 ..catchError((error) { |
| 196 logger.severe('Error: Failed to create mirror system. '); | 197 logger.severe('Error: Failed to create mirror system. '); |
| (...skipping 473 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 670 String name; | 671 String name; |
| 671 String type; | 672 String type; |
| 672 | 673 |
| 673 Generic(this.name, this.type); | 674 Generic(this.name, this.type); |
| 674 | 675 |
| 675 Map toMap() => { | 676 Map toMap() => { |
| 676 'name': name, | 677 'name': name, |
| 677 'type': type | 678 'type': type |
| 678 }; | 679 }; |
| 679 } | 680 } |
| OLD | NEW |