OLD | NEW |
1 // Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2014, 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 library docgen.generator; | 5 library docgen.generator; |
6 | 6 |
7 import 'dart:async'; | 7 import 'dart:async'; |
8 import 'dart:collection'; | 8 import 'dart:collection'; |
9 import 'dart:convert'; | 9 import 'dart:convert'; |
10 import 'dart:io'; | 10 import 'dart:io'; |
(...skipping 23 matching lines...) Expand all Loading... |
34 String get outputDirectory => _outputDirectory; | 34 String get outputDirectory => _outputDirectory; |
35 String _outputDirectory; | 35 String _outputDirectory; |
36 | 36 |
37 /// Library names to explicitly exclude. | 37 /// Library names to explicitly exclude. |
38 /// | 38 /// |
39 /// Set from the command line option | 39 /// Set from the command line option |
40 /// --exclude-lib. | 40 /// --exclude-lib. |
41 List<String> _excluded; | 41 List<String> _excluded; |
42 | 42 |
43 /// The path of the pub script. | 43 /// The path of the pub script. |
44 String get pubScript => _pubScript; | 44 String pubScript; |
45 String _pubScript; | |
46 | 45 |
47 /// The path of Dart binary. | 46 /// The path of Dart binary. |
48 String get dartBinary => _dartBinary; | 47 String dartBinary; |
49 String _dartBinary; | |
50 | 48 |
51 /// Docgen constructor initializes the link resolver for markdown parsing. | 49 /// Docgen constructor initializes the link resolver for markdown parsing. |
52 /// Also initializes the command line arguments. | 50 /// Also initializes the command line arguments. |
53 /// | 51 /// |
54 /// [packageRoot] is the packages directory of the directory being analyzed. | 52 /// [packageRoot] is the packages directory of the directory being analyzed. |
55 /// If [includeSdk] is `true`, then any SDK libraries explicitly imported will | 53 /// If [includeSdk] is `true`, then any SDK libraries explicitly imported will |
56 /// also be documented. | 54 /// also be documented. |
57 /// If [parseSdk] is `true`, then all Dart SDK libraries will be documented. | 55 /// If [parseSdk] is `true`, then all Dart SDK libraries will be documented. |
58 /// This option is useful when only the SDK libraries are needed. | 56 /// This option is useful when only the SDK libraries are needed. |
59 /// | 57 /// |
60 /// Returned Future completes with true if document generation is successful. | 58 /// Returned Future completes with true if document generation is successful. |
61 Future<bool> generateDocumentation(List<String> files, {String packageRoot, | 59 Future<bool> generateDocumentation(List<String> files, {String packageRoot, |
62 bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false, | 60 bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false, |
63 bool parseSdk: false, String introFileName: '', | 61 bool parseSdk: false, String introFileName: '', |
64 out: DEFAULT_OUTPUT_DIRECTORY, List<String> excludeLibraries: const [], bool | 62 out: DEFAULT_OUTPUT_DIRECTORY, List<String> excludeLibraries: const [], bool |
65 includeDependentPackages: false, String startPage, String dartBinary, | 63 includeDependentPackages: false, String startPage, String dartBinaryValue, |
66 String pubScript, bool indentJSON: false}) { | 64 String pubScriptValue, bool indentJSON: false}) { |
67 _excluded = excludeLibraries; | 65 _excluded = excludeLibraries; |
68 _pubScript = pubScript; | 66 dartBinary = dartBinaryValue; |
69 _dartBinary = dartBinary; | 67 pubScript = pubScriptValue; |
70 | 68 |
71 logger.onRecord.listen((record) => print(record.message)); | 69 logger.onRecord.listen((record) => print(record.message)); |
72 | 70 |
73 _ensureOutputDirectory(out); | 71 _ensureOutputDirectory(out); |
74 var updatedPackageRoot = _obtainPackageRoot(packageRoot, parseSdk, files); | 72 var updatedPackageRoot = _obtainPackageRoot(packageRoot, parseSdk, files); |
75 | 73 |
76 var requestedLibraries = _findLibrariesToDocument(files, | 74 var requestedLibraries = _findLibrariesToDocument(files, |
77 includeDependentPackages); | 75 includeDependentPackages); |
78 | 76 |
79 var allLibraries = []..addAll(requestedLibraries); | 77 var allLibraries = []..addAll(requestedLibraries); |
(...skipping 297 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
377 } else { | 375 } else { |
378 return entities; | 376 return entities; |
379 } | 377 } |
380 } | 378 } |
381 | 379 |
382 /// All of the directories for our dependent packages | 380 /// All of the directories for our dependent packages |
383 /// If this is not a package, return an empty list. | 381 /// If this is not a package, return an empty list. |
384 List<String> _allDependentPackageDirs(String packageDirectory) { | 382 List<String> _allDependentPackageDirs(String packageDirectory) { |
385 var packageName = packageNameFor(packageDirectory); | 383 var packageName = packageNameFor(packageDirectory); |
386 if (packageName == '') return []; | 384 if (packageName == '') return []; |
387 var dependentsJson = Process.runSync(_pubScript, ['list-package-dirs'], | 385 var dependentsJson = Process.runSync(pubScript, ['list-package-dirs'], |
388 workingDirectory: packageDirectory, runInShell: true); | 386 workingDirectory: packageDirectory, runInShell: true); |
389 if (dependentsJson.exitCode != 0) { | 387 if (dependentsJson.exitCode != 0) { |
390 print(dependentsJson.stderr); | 388 print(dependentsJson.stderr); |
391 } | 389 } |
392 var dependents = JSON.decode(dependentsJson.stdout)['packages']; | 390 var dependents = JSON.decode(dependentsJson.stdout)['packages']; |
393 return dependents.values.toList(); | 391 return dependents != null ? dependents.values.toList() : []; |
394 } | 392 } |
395 | 393 |
396 /// For all the libraries, return a list of the libraries that are part of | 394 /// For all the libraries, return a list of the libraries that are part of |
397 /// the SDK. | 395 /// the SDK. |
398 List<Uri> _listSdk() { | 396 List<Uri> _listSdk() { |
399 var sdk = new List<Uri>(); | 397 var sdk = new List<Uri>(); |
400 LIBRARIES.forEach((String name, LibraryInfo info) { | 398 LIBRARIES.forEach((String name, LibraryInfo info) { |
401 if (info.documented) { | 399 if (info.documented) { |
402 sdk.add(Uri.parse('dart:$name')); | 400 sdk.add(Uri.parse('dart:$name')); |
403 logger.info('Add to SDK: ${sdk.last}'); | 401 logger.info('Add to SDK: ${sdk.last}'); |
(...skipping 53 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
457 * [Samples](http://www.dartlang.org/samples/) | 455 * [Samples](http://www.dartlang.org/samples/) |
458 * [A Tour of the Dart Libraries](http://www.dartlang.org/docs/dart-up-and-runn
ing/contents/ch03.html) | 456 * [A Tour of the Dart Libraries](http://www.dartlang.org/docs/dart-up-and-runn
ing/contents/ch03.html) |
459 | 457 |
460 This API reference is automatically generated from the source code in the | 458 This API reference is automatically generated from the source code in the |
461 [Dart project](https://code.google.com/p/dart/). | 459 [Dart project](https://code.google.com/p/dart/). |
462 If you'd like to contribute to this documentation, see | 460 If you'd like to contribute to this documentation, see |
463 [Contributing](https://code.google.com/p/dart/wiki/Contributing) | 461 [Contributing](https://code.google.com/p/dart/wiki/Contributing) |
464 and | 462 and |
465 [Writing API Documentation](https://code.google.com/p/dart/wiki/WritingApiDocume
ntation). | 463 [Writing API Documentation](https://code.google.com/p/dart/wiki/WritingApiDocume
ntation). |
466 """; | 464 """; |
OLD | NEW |