Generate docgen output along with api_docs as part of the build

pkg/docgen/lib/docgen.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /// **docgen** is a tool for creating machine readable representations of Dart
 /// code metadata, including: classes, members, comments and annotations.
 ///
 /// docgen is run on a `.dart` file or a directory containing `.dart` files.
 ///
 ///      $ dart docgen.dart [OPTIONS] [FILE/DIR]
@@ skipping 18 matching lines @@
 import '../../../sdk/lib/_internal/compiler/implementation/mirrors/dart2js_mirror.dart'
     as dart2js;
 import '../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors.dart';
 import '../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dart'
     as dart2js_util;
 import '../../../sdk/lib/_internal/compiler/implementation/source_file_provider.dart';
 import '../../../sdk/lib/_internal/libraries.dart';
 
 var logger = new Logger('Docgen');
 
+var outputDirectory = 'docs';

[kustermann, 2013/11/18 09:57:08]

Why are some other global variables a few lines down marked with an "_" (i.e.
library private) and this one is not?

Will these variables be accessed from somewher else?

[Alan Knight, 2013/11/18 20:34:50]

Made it private.

+
 const String USAGE = 'Usage: dart docgen.dart [OPTIONS] fooDir/barFile';
 
 
 List<String> skippedAnnotations = const [
     'metadata.DocsEditable', '_js_helper.JSName', '_js_helper.Creates',
     '_js_helper.Returns'];
 
 /// Set of libraries declared in the SDK, so libraries that can be accessed
 /// when running dart by default.
 Iterable<LibraryMirror> _sdkLibraries;
@@ skipping 18 matching lines @@
 /// Resolves reference links in doc comments.
 markdown.Resolver linkResolver;
 
 /// Index of all indexable items. This also ensures that no class is
 /// created more than once.
 Map<String, Indexable> entityMap = new Map<String, Indexable>();
 
 /// This is set from the command line arguments flag --include-private
 bool _includePrivate = false;
 
+/// Library names to explicitly exclude.
+///
+///   Set from the command line option
+/// --exclude-lib.
+List<String> _excluded;
+
 // TODO(janicejl): Make MDN content generic or pluggable. Maybe move
 // MDN-specific code to its own library that is imported into the default impl?
 /// Map of all the comments for dom elements from MDN.
 Map _mdn;
 
 /// Docgen constructor initializes the link resolver for markdown parsing.
 /// Also initializes the command line arguments.
 ///
 /// [packageRoot] is the packages directory of the directory being analyzed.
 /// If [includeSdk] is `true`, then any SDK libraries explicitly imported will
 /// also be documented.
 /// If [parseSdk] is `true`, then all Dart SDK libraries will be documented.
 /// This option is useful when only the SDK libraries are needed.
 ///
 /// Returned Future completes with true if document generation is successful.
 Future<bool> docgen(List<String> files, {String packageRoot,
     bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false,
-    bool parseSdk: false, bool append: false, String introduction: ''}) {
+    bool parseSdk: false, bool append: false, String introduction: '',
+    out: 'docs', List<String> excludeLibraries}) {

[kustermann, 2013/11/18 09:57:08]

It's slightly strange that we have the default value 'docs' here *and* at line
39 (i.e. for the global outputDirectory variable).

[Alan Knight, 2013/11/18 20:34:50]

Yes. I can't default the parameter to a variable value, but made a constant and
defaulted it to that. Removed the default value for the variable, as it is
always and only ever initialized in this call.

+  _excluded = excludeLibraries;
   _includePrivate = includePrivate;
+  outputDirectory = out;
   if (!append) {
-    var dir = new Directory('docs');
+    var dir = new Directory(outputDirectory);
     if (dir.existsSync()) dir.deleteSync(recursive: true);
   }
 
   if (packageRoot == null && !parseSdk) {
     var type = FileSystemEntity.typeSync(files.first);
     if (type == FileSystemEntityType.DIRECTORY) {
       packageRoot = _findPackageRoot(files.first);
     } else if (type == FileSystemEntityType.FILE) {
       logger.warning('WARNING: No package root defined. If Docgen fails, try '
           'again by setting the --package-root option.');
     }
   }
   logger.info('Package Root: ${packageRoot}');
   linkResolver = (name) =>
       fixReference(name, _currentLibrary, _currentClass, _currentMember);
+  var requestedLibraries = !parseSdk ? _listLibraries(files) : _listSdk();
 
-  return getMirrorSystem(files, packageRoot: packageRoot, parseSdk: parseSdk)
+  return getMirrorSystem(requestedLibraries, packageRoot: packageRoot,
+      parseSdk: parseSdk)
     .then((MirrorSystem mirrorSystem) {
       if (mirrorSystem.libraries.isEmpty) {
         throw new StateError('No library mirrors were created.');
       }
-      var librariesWeAskedFor = _listLibraries(files);
-      var librariesWeGot = mirrorSystem.libraries.values.where(
+      var availableLibraries = mirrorSystem.libraries.values.where(
           (each) => each.uri.scheme == 'file');
       _sdkLibraries = mirrorSystem.libraries.values.where(
           (each) => each.uri.scheme == 'dart');
       _coreLibrary = _sdkLibraries.singleWhere((lib) =>
           lib.uri.toString().startsWith('dart:core'));
-      var librariesWeGotByPath = new Map.fromIterables(
-          librariesWeGot.map((each) => each.uri.toFilePath()),
-          librariesWeGot);
-      var librariesToDocument = librariesWeAskedFor.map(
-          (each) => librariesWeGotByPath.putIfAbsent(each,
+      var availableLibrariesByPath = new Map.fromIterables(
+          availableLibraries.map((each) => each.uri.toFilePath()),
+          availableLibraries);
+      var librariesToDocument = requestedLibraries.map(
+          (each) => availableLibrariesByPath.putIfAbsent(each,
               () => throw "Missing library $each")).toList();
       librariesToDocument.addAll((includeSdk || parseSdk) ? _sdkLibraries : []);
+      librariesToDocument.removeWhere((x) => _excluded.contains(x.simpleName));
       _documentLibraries(librariesToDocument, includeSdk: includeSdk,
           outputToYaml: outputToYaml, append: append, parseSdk: parseSdk,
           introduction: introduction);
       return true;
     });
 }
 
 /// For a library's [mirror], determine the name of the package (if any) we
 /// believe it came from (because of its file URI).
 ///
@@ skipping 28 matching lines @@
   if (readmes.isEmpty) return '';
   // If there are multiples, pick the shortest name.
   readmes.sort((a, b) => a.length.compareTo(b.length));
   var readme = readmes.first;
   var contents = markdown.markdownToHtml(readme
     .readAsStringSync(), linkResolver: linkResolver,
     inlineSyntaxes: markdownSyntaxes);
   return contents;
 }
 
-
 List<String> _listLibraries(List<String> args) {
   var libraries = new List<String>();
   for (var arg in args) {
     var type = FileSystemEntity.typeSync(arg);
 
     if (type == FileSystemEntityType.FILE) {
       if (arg.endsWith('.dart')) {
         libraries.add(path.absolute(arg));
         logger.info('Added to libraries: ${libraries.last}');
       }
@@ skipping 19 matching lines @@
       // Only add the file if it does not contain 'part of'
       // TODO(janicejl): Remove when Issue(12406) is resolved.
       var contents = new File(f).readAsStringSync();
       if (!(contents.contains(new RegExp('\npart of ')) ||
           contents.startsWith(new RegExp('part of ')))) {
         libraries.add(f);
         logger.info('Added to libraries: $f');
       }
     }
   });
-  return libraries;
+  return libraries.map(path.absolute).map(path.normalize).toList();
 }
 
 String _findPackageRoot(String directory) {
   var files = listDir(directory, recursive: true);
   // Return '' means that there was no pubspec.yaml and therefor no packageRoot.
   String packageRoot = files.firstWhere((f) =>
       f.endsWith('${path.separator}pubspec.yaml'), orElse: () => '');
   if (packageRoot != '') {
     packageRoot = path.join(path.dirname(packageRoot), 'packages');
   }
@@ skipping 15 matching lines @@
     if (info.documented) {
       sdk.add('dart:$name');
       logger.info('Add to SDK: ${sdk.last}');
     }
   });
   return sdk;
 }
 
 /// Analyzes set of libraries by getting a mirror system and triggers the
 /// documentation of the libraries.
-Future<MirrorSystem> getMirrorSystem(List<String> args, {String packageRoot,
-    bool parseSdk: false}) {
-  var libraries = !parseSdk ? _listLibraries(args) : _listSdk();
+Future<MirrorSystem> getMirrorSystem(List<String> libraries,
+    {String packageRoot, bool parseSdk: false}) {
   if (libraries.isEmpty) throw new StateError('No Libraries.');
   // Finds the root of SDK library based off the location of docgen.
 
   var root = findRootDirectory();
   var sdkRoot = path.normalize(path.absolute(path.join(root, 'sdk')));
   logger.info('SDK Root: ${sdkRoot}');
   return _analyzeLibraries(libraries, sdkRoot, packageRoot: packageRoot);
 }
 
 String findRootDirectory() {
@@ skipping 54 matching lines @@
   // Everything is a subclass of Object, therefore empty the list to avoid a
   // giant list of subclasses to be printed out.
   if (includeSdk) (entityMap['dart-core.Object'] as Class).subclasses.clear();
 
   var filteredEntities = entityMap.values.where(_isVisible);
 
   // Outputs a JSON file with all libraries and their preview comments.
   // This will help the viewer know what libraries are available to read in.
   var libraryMap;
   if (append) {
-    var docsDir = listDir('docs');
-    if (!docsDir.contains('docs/library_list.json')) {
+    var docsDir = listDir(outputDirectory);
+    if (!docsDir.contains('$outputDirectory/library_list.json')) {
       throw new StateError('No library_list.json');
     }
     libraryMap =
-        JSON.decode(new File('docs/library_list.json').readAsStringSync());
+        JSON.decode(new File('$outputDirectory/library_list.json').readAsStringSync());
     libraryMap['libraries'].addAll(filteredEntities
         .where((e) => e is Library)
         .map((e) => e.previewMap));
     if (introduction.isNotEmpty) {
       var intro = libraryMap['introduction'];
       if (intro.isNotEmpty) intro += '<br/><br/>';
       intro += markdown.markdownToHtml(
           new File(introduction).readAsStringSync(),
               linkResolver: linkResolver, inlineSyntaxes: markdownSyntaxes);
       libraryMap['introduction'] = intro;
@@ skipping 20 matching lines @@
   // Outputs all the qualified names documented with their type.
   // This will help generate search results.
   _writeToFile(filteredEntities.map((e) =>
       '${e.qualifiedName} ${e.typeName}').join('\n') + '\n',
       'index.txt', append: append);
   var index = new Map.fromIterables(
       filteredEntities.map((e) => e.qualifiedName),
       filteredEntities.map((e) => e.typeName));
   if (append) {
     var previousIndex =
-        JSON.decode(new File('docs/index.json').readAsStringSync());
+        JSON.decode(new File('$outputDirectory/index.json').readAsStringSync());
     index.addAll(previousIndex);
   }
   _writeToFile(JSON.encode(index), 'index.json');
 }
 
 Library generateLibrary(dart2js.Dart2JsLibraryMirror library) {
   _currentLibrary = library;
   var result = new Library(docName(library), _commentToHtml(library),
       _classes(library.classes),
       _methods(library.functions),
@@ skipping 374 matching lines @@
   if (mirror is ClassMirror && !mirror.isTypedef) {
     var innerList = [];
     mirror.typeArguments.forEach((e) {
       innerList.add(new Type(docName(e), _typeGenerics(e)));
     });
     return innerList;
   }
   return [];
 }
 
-/// Writes text to a file in the 'docs' directory.
+/// Writes text to a file in the output directory.
 void _writeToFile(String text, String filename, {bool append: false}) {
-  Directory dir = new Directory('docs');
+  if (text == null) return;
+  Directory dir = new Directory(outputDirectory);
   if (!dir.existsSync()) {
     dir.createSync();
   }
   // We assume there's a single extra level of directory structure for packages.
   if (path.split(filename).length > 1) {
-    var subdir = new Directory(path.join('docs', path.dirname(filename)));
+    var subdir = new Directory(path.join(outputDirectory, path.dirname(filename)));
     if (!subdir.existsSync()) {
       subdir.createSync();
     }
   }
-
-  File file = new File('docs/$filename');
-  if (!file.existsSync()) {
-    file.createSync();
-  }
+  File file = new File(path.join(outputDirectory, filename));
   file.writeAsStringSync(text, mode: append ? FileMode.APPEND : FileMode.WRITE);
 }
 
 /// Transforms the map by calling toMap on each value in it.
 Map recurseMap(Map inputMap) {
   var outputMap = {};
   inputMap.forEach((key, value) {
     if (value is Map) {
       outputMap[key] = recurseMap(value);
     } else {
@@ skipping 593 matching lines @@
 /// Remove statics from the map of inherited items before adding them.
 Map _filterStatics(Map items) {
   var result = {};
   items.forEach((name, item) {
     if (!item.isStatic) {
       result[name] = item;
     }
   });
   return result;
 }