Added an introduction option by passing in a file with markdown.

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.
  *
@@ skipping 61 matching lines @@
  * [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.
  *
  * Returns `true` if docgen sucessfuly completes.
  */
 Future<bool> docgen(List<String> files, {String packageRoot,
     bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false,
-    bool parseSdk: false, bool append: false}) {
+    bool parseSdk: false, bool append: false, String introduction: ''}) {
   _includePrivate = includePrivate;
   if (!append) {
     var dir = new Directory('docs');
     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);
 
   return getMirrorSystem(files, packageRoot: packageRoot, parseSdk: parseSdk)
     .then((MirrorSystem mirrorSystem) {
       if (mirrorSystem.libraries.isEmpty) {
         throw new StateError('No library mirrors were created.');
       }
       _documentLibraries(mirrorSystem.libraries.values,includeSdk: includeSdk,
-          outputToYaml: outputToYaml, append: append, parseSdk: parseSdk);
+          outputToYaml: outputToYaml, append: append, parseSdk: parseSdk, 
+          introduction: introduction);
 
       return true;
     });
 }
 
 List<String> _listLibraries(List<String> args) {
   if (args.length != 1) throw new UnsupportedError(USAGE);
   var libraries = new List<String>();
   var type = FileSystemEntity.typeSync(args[0]);
 
@@ skipping 95 matching lines @@
         // system, and it is not possible to use the stack trace. BUG(#11622)
         // To avoid printing the stack trace.
         exit(1);
       });
 }
 
 /**
  * Creates documentation for filtered libraries.
  */
 void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false,
-    bool outputToYaml: true, bool append: false, bool parseSdk: false}) {
+    bool outputToYaml: true, bool append: false, bool parseSdk: false, 
+    String introduction: ''}) {
   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);
       entityMap[library.qualifiedName] = library;
     }
   });
   // After everything is created, do a pass through all classes to make sure no
   // intermediate classes created by mixins are included.
   entityMap.values.where((e) => e is Class).forEach((c) => c.makeValid());
   // Everything is a subclass of Object, therefore empty the list to avoid a
   // giant list of subclasses to be printed out.
   if (parseSdk) entityMap['dart.core.Object'].subclasses.clear();
 
   var filteredEntities = entityMap.values.where(_isVisible);
   // 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);
   });
+  var intro = introduction == '' ? 

[Emily Fortuna, 2013/08/15 18:39:35]

any reason why you define a new variable here instead of just assigning a new
value to introduction?

[janicejl, 2013/08/15 18:45:59]

Done. Moved it down to the map instead. 

+      '' : markdown.markdownToHtml(new File(introduction).readAsStringSync(),
+          linkResolver: linkResolver, inlineSyntaxes: markdownSyntaxes);
   // Outputs a yaml file with all libraries and their preview comments after 
   // creating all libraries. This will help the viewer know what libraries are 
   // available to read in.
-  var libraryMap = {'libraries' : filteredEntities.where((e) => 
-      e is Library).map((e) => e.previewMap).toList()};
+  var libraryMap = {
+    'libraries' : filteredEntities.where((e) => 
+        e is Library).map((e) => e.previewMap).toList(),
+    'introduction' : intro
+  };
   _writeToFile(getYamlString(libraryMap), 'library_list.yaml', append: append);
   // 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'),
       'index.txt', append: append);
 }
 
 Library generateLibrary(dart2js.Dart2JsLibraryMirror library) {
   _currentLibrary = library;
@@ skipping 827 matching lines @@
   String qualifiedName;
   List<String> parameters;
 
   Annotation(this.qualifiedName, this.parameters);
 
   Map toMap() => {
     'name': qualifiedName,
     'parameters': parameters
   };
 }