pkg/docgen: more cleanup

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 340 matching lines @@
         linkResolver: linkResolver, inlineSyntaxes: _MARKDOWN_SYNTAXES);
   }
 
   /// Creates documentation for filtered libraries.
   static void _documentLibraries(List<LibraryMirror> libs,
       {bool includeSdk: false, bool outputToYaml: true, bool append: false,
        bool parseSdk: false, String introFileName: '', String startPage}) {
     libs.forEach((lib) {
       // Files belonging to the SDK have a uri that begins with 'dart:'.
       if (includeSdk || !lib.uri.toString().startsWith('dart:')) {
-        var library = generateLibrary(lib);
+        generateLibrary(lib);
       }
     });
 
     var filteredEntities = new Set<Indexable>();
     for (Map<String, Set<Indexable>> firstLevel in
         Indexable._mirrorToDocgen.values) {
       for (Set<Indexable> items in firstLevel.values) {
         for (Indexable item in items) {
           if (_isFullChainVisible(item)) {
             if (item is! Method ||
                 (item is Method && item.methodInheritedFrom == null)) {
               filteredEntities.add(item);
             }
           }
         }
       }
     }
 
     // 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;
+    Map<String, dynamic> libraryMap;
 
     if (append) {
       var docsDir = listDir(_outputDirectory);
       if (!docsDir.contains('$_outputDirectory/library_list.json')) {
         throw new StateError('No library_list.json');
       }
       libraryMap =
           JSON.decode(new File(
               '$_outputDirectory/library_list.json').readAsStringSync());
       libraryMap['libraries'].addAll(filteredEntities
@@ skipping 11 matching lines @@
         'introduction' : _readIntroductionFile(introFileName, includeSdk),
         'filetype' : outputToYaml ? 'yaml' : 'json'
       };
     }
     _writeOutputFiles(libraryMap, filteredEntities, outputToYaml, append,
         startPage);
   }
 
   /// Output all of the libraries and classes into json or yaml files for
   /// consumption by a viewer.
-  static void _writeOutputFiles(libraryMap,
+  static void _writeOutputFiles(Map<String, dynamic> libraryMap,
       Iterable<Indexable> filteredEntities, bool outputToYaml, bool append,
       String startPage) {
     if (startPage != null) libraryMap['start-page'] = startPage;
 
     _writeToFile(JSON.encode(libraryMap), 'library_list.json');
 
     // Output libraries and classes to file after all information is generated.
     filteredEntities.where((e) => e is Class || e is Library).forEach((output) {
       _writeIndexableToFile(output, outputToYaml);
     });
@@ skipping 126 matching lines @@
   static List<Uri> _findLibrariesToDocument(List<String> args,
       bool includeDependentPackages) {
     if (includeDependentPackages) {
       args.addAll(_allDependentPackageDirs(args.first));
     }
 
     var libraries = new List<Uri>();
     for (var arg in args) {
       if (FileSystemEntity.typeSync(arg) == FileSystemEntityType.FILE) {
         if (arg.endsWith('.dart')) {
-          libraries.add(new Uri.file(path.absolute(arg)));
-          logger.info('Added to libraries: ${libraries.last}');
+          var f = new Uri.file(path.absolute(arg));

[Emily Fortuna, 2014/03/17 17:54:31]

I dislike single letter variable names outside of for loops. 

[kevmoo, 2014/03/17 20:13:03]

Done.

+          libraries.add(f);
+          logger.info('Added to libraries: $f');
         }
       } else {
         libraries.addAll(_findFilesToDocumentInPackage(arg));
       }
     }
     return libraries;
   }
 
   /// Given a package name, explore the directory and pull out all top level
   /// library files in the "lib" directory to document.
@@ skipping 49 matching lines @@
     return sdk;
   }
 
   /// Return true if this item and all of its owners are all visible.
   static bool _isFullChainVisible(Indexable item) {
     return _includePrivate || (!item.isPrivate && (item.owner != null ?
         _isFullChainVisible(item.owner) : true));
   }
 
   /// Currently left public for testing purposes. :-/
-  static Library generateLibrary(dart2js_mirrors.Dart2JsLibraryMirror library) {
+  static void generateLibrary(dart2js_mirrors.Dart2JsLibraryMirror library) {
     var result = new Library(library);
-    result._findPackage(library);
+    result._updateLibraryPackage(library);
     logger.fine('Generated library for ${result.name}');
-    return result;
   }
 }
 
 /// Convenience methods wrapped up in a class to pull down the docgen viewer for
 /// a viewable website, and start up a server for viewing.
 class _Viewer {
   static String _dartdocViewerString = path.join(Directory.current.path,
       'dartdoc-viewer');
   static Directory _dartdocViewerDir = new Directory(_dartdocViewerString);
   static Directory _topLevelTempDir;
@@ skipping 562 matching lines @@
     return new DummyMirror(mirror, owner);
   }
 
   /// Returns true if [mirror] is the correct type of mirror that this Docgen
   /// object wraps. (Workaround for the fact that Types are not first class.)
   bool _isValidMirror(DeclarationMirror mirror);
 }
 
 /// A class containing contents of a Dart library.
 class Library extends Indexable {
+  final Map<String, Class> classes = {};
+  final Map<String, Typedef> typedefs = {};
+  final Map<String, Class> errors = {};
 
   /// Top-level variables in the library.
   Map<String, Variable> variables;
 
   /// Top-level functions in the library.
   Map<String, Method> functions;
 
-  Map<String, Class> classes = {};
-  Map<String, Typedef> typedefs = {};
-  Map<String, Class> errors = {};
-
   String packageName = '';
   bool _hasBeenCheckedForPackage = false;
   String packageIntro;
 
   Library get _owningLibrary => this;
 
   /// Returns the [Library] for the given [mirror] if it has already been
   /// created, else creates it.
   factory Library(LibraryMirror mirror) {
     var library = Indexable.getDocgenObject(mirror);
     if (library is DummyMirror) {
       library = new Library._(mirror);
     }
     return library;
   }
 
   Library._(LibraryMirror libraryMirror) : super(libraryMirror) {
     var exported = _calcExportedItems(libraryMirror);
     var exportedClasses = _addAll(exported['classes'],
         dart2js_util.typesOf(libraryMirror.declarations));
-    _findPackage(mirror);
-    classes = {};
-    typedefs = {};
-    errors = {};
+    _updateLibraryPackage(mirror);
     exportedClasses.forEach((String mirrorName, TypeMirror mirror) {
         if (mirror is TypedefMirror) {
           // This is actually a Dart2jsTypedefMirror, and it does define value,
           // but we don't have visibility to that type.
           if (_Generator._includePrivate || !mirror.isPrivate) {
             typedefs[dart2js_util.nameOf(mirror)] = new Typedef(mirror, this);
           }
         } else if (mirror is ClassMirror) {
           var clazz = new Class(mirror, this);
 
@@ skipping 23 matching lines @@
       var result = Indexable.getDocgenObject(libraryScope, this);
       if (result is DummyMirror) return packagePrefix + result.docName;
       return result.packagePrefix + result.docName;
     }
     return super.findElementInScope(name);
   }
 
   String _mdnComment() => '';
 
   /// Helper that maps [mirrors] to their simple name in map.
-  Map _addAll(Map map, Iterable<DeclarationMirror> mirrors) {
+  static Map _addAll(Map map, Iterable<DeclarationMirror> mirrors) {
     for (var mirror in mirrors) {
       map[dart2js_util.nameOf(mirror)] = mirror;
     }
     return map;
   }
 
   /// For a library's [mirror], determine the name of the package (if any) we
   /// believe it came from (because of its file URI).
   ///
   /// If no package could be determined, we return an empty string.
-  String _findPackage(LibraryMirror mirror) {
-    if (mirror == null) return '';
-    if (_hasBeenCheckedForPackage) return packageName;
+  void _updateLibraryPackage(LibraryMirror mirror) {
+    if (mirror == null) return;
+    if (_hasBeenCheckedForPackage) return;
     _hasBeenCheckedForPackage = true;
-    if (mirror.uri.scheme != 'file') return '';
+    if (mirror.uri.scheme != 'file') return;
     packageName = _packageName(mirror);
     // Associate the package readme with all the libraries. This is a bit
     // wasteful, but easier than trying to figure out which partial match
     // is best.
     packageIntro = _packageIntro(_getPackageDirectory(mirror));
-    return packageName;
   }
 
   String _packageIntro(packageDir) {
     if (packageDir == null) return null;
     var dir = new Directory(packageDir);
     var files = dir.listSync();
     var readmes = files.where((FileSystemEntity each) => (each is File &&
         each.path.substring(packageDir.length + 1, each.path.length)
           .startsWith('README'))).toList();
     if (readmes.isEmpty) return '';
@@ skipping 822 matching lines @@
   var annotations = [];
   annotationMirrors.forEach((annotation) {
     var docgenAnnotation = new Annotation(annotation, owningLibrary);
     if (!_SKIPPED_ANNOTATIONS.contains(
         dart2js_util.qualifiedNameOf(docgenAnnotation.mirror))) {
       annotations.add(docgenAnnotation);
     }
   });
   return annotations;
 }