pkg/docgen: removed py files, doc/README.txt, fixed analyzer warning

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 99 matching lines @@
 /// viewer with dart2js.
 /// If [serve] is `true`, then after generating the documents we fire up a
 /// simple server to view the documentation.
 ///
 /// 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 introFileName: '',
     out: _DEFAULT_OUTPUT_DIRECTORY, List<String> excludeLibraries : const [],
     bool includeDependentPackages: false, bool compile: false, bool serve: false,
-    bool noDocs: false, String startPage, 
+    bool noDocs: false, String startPage,
     String pubScript, String dartBinary}) {
   var result;
   if (!noDocs) {
     _Viewer.ensureMovedViewerCode();
     result = _Generator.generateDocumentation(files, packageRoot: packageRoot,
         outputToYaml: outputToYaml, includePrivate: includePrivate,
         includeSdk: includeSdk, parseSdk: parseSdk, append: append,
         introFileName: introFileName, out: out,
         excludeLibraries: excludeLibraries,
         includeDependentPackages: includeDependentPackages,
         startPage: startPage, pubScript: pubScript, dartBinary: dartBinary);
     _Viewer.addBackViewerCode();
     if (compile || serve) {
       result.then((success) {
         if (success) {
           _createViewer(serve);
         }
       });
-    } 
+    }
   } else if (compile || serve) {
     _createViewer(serve);
   }
   return result;
 }
 
 void _createViewer(bool serve) {
   _Viewer._clone();
   _Viewer._compile();
   if (serve) {
      _Viewer._runServer();
    }
-} 
+}
 
 /// Analyzes set of libraries by getting a mirror system and triggers the
 /// documentation of the libraries.
 Future<MirrorSystem> getMirrorSystem(List<Uri> 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.
   // We have two different places to look, depending if we're in a development
   // repo or in a built SDK, either sdk or dart-sdk respectively
@@ skipping 526 matching lines @@
     }
     else {
       var processResult = Process.runSync('git', ['clone', '-b', 'master',
           'git://github.com/dart-lang/dartdoc-viewer.git'],
           runInShell: true);
 
       if (processResult.exitCode == 0) {
         /// Move the generated json/yaml docs directory to the dartdoc-viewer
         /// directory, to run as a webpage.
         var processResult = Process.runSync(_Generator._pubScript,
-            ['upgrade'], runInShell: true, 
+            ['upgrade'], runInShell: true,
             workingDirectory: path.join(_dartdocViewerDir.path, 'client'));
         print('process output: ${processResult.stdout}');
         print('process stderr: ${processResult.stderr}');
 
         var dir = new Directory(_Generator._outputDirectory == null? 'docs' :
             _Generator._outputDirectory);
         _webDocsDir = new Directory(path.join(_dartdocViewerDir.path, 'client',
             'web', 'docs'));
         if (dir.existsSync()) {
           // Move the docs folder to dartdoc-viewer/client/web/docs
@@ skipping 872 matching lines @@
       }
     }
     var domAnnotation = this.annotations.firstWhere(
         (e) => e.mirror.qualifiedName == #metadata.DomName,
         orElse: () => null);
     if (domAnnotation == null) return '';
     var domName = domAnnotation.parameters.single;
     var parts = domName.split('.');
     if (parts.length == 2) return _mdnMemberComment(parts[0], parts[1]);
     if (parts.length == 1) return _mdnTypeComment(parts[0]);
+
+    throw new StateError('More than two items is not supported: $parts');

[kevmoo, 2014/02/17 20:27:21]

Going with being strict. If the code isn't designed to handle a count that is
not 1 or 2, better to throw than to assume a valid behavior.

   }
 
   String get packagePrefix => owner.packagePrefix;
 }
 
 /// A class containing contents of a Dart class.
 class Class extends OwnedIndexable implements Comparable {
 
   /// List of the names of interfaces that this class implements.
   List<Class> interfaces = [];
@@ skipping 596 matching lines @@
         .map((e) => originalMirror.getField(e.simpleName).reflectee)
         .where((e) => e != null)
         .toList();
   }
 
   Map toMap() => {
     'name': Indexable.getDocgenObject(mirror, owningLibrary).docName,
     'parameters': parameters
   };
 }