Added markdown reference recognition and output to JSON.

pkg/docgen/bin/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.
+
 /**
  * The docgen tool takes in a library as input and produces documentation
  * for the library as well as all libraries it imports and uses. The tool can
  * be run by passing in the path to a .dart file like this:
  *
  *   ./dart docgen.dart path/to/file.dart
  *
  * This outputs information about all classes, variables, functions, and
  * methods defined in the library and its imported libraries.
  */
 library docgen;
 
+// TODO(tmandel): Use 'package:' references for imports with relative paths.
 import 'dart:io';
+import 'dart:json';
 import 'dart:async';
 import '../lib/dart2yaml.dart';
 import '../lib/src/dart2js_mirrors.dart';
 import 'package:markdown/markdown.dart' as markdown;
 import '../../args/lib/args.dart';
 import '../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors.dart';
 import '../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dart';
 
 /**
  * Entry function to create YAML documentation from Dart files.
@@ skipping 33 matching lines @@
   
   /// Current library being documented to be used for comment links.
   LibraryMirror _currentLibrary;
   
   /// Current class being documented to be used for comment links.
   ClassMirror _currentClass;
   
   /// Current member being documented to be used for comment links.
   MemberMirror _currentMember;
   
+  /// Should the output file type be JSON?
+  // TODO(tmandel): Add flag to allow for output to JSON.
+  bool outputToJson = false;
+  
+  /// Resolves reference links
+  markdown.Resolver linkResolver;
+  
+  /**
+   * Docgen constructor initializes the link resolver for markdown parsing.
+   */
+  Docgen() {
+    this.linkResolver = (name) => 
+        fixReference(name, _currentLibrary, _currentClass, _currentMember);
+  }
+  
   /**
    * Creates documentation for filtered libraries.
    */
   void documentLibraries() {
     //TODO(tmandel): Filter libraries and determine output type using flags.
     _libraries.forEach((library) {
       _currentLibrary = library;
       var result = new Library(library.qualifiedName, _getComment(library),
           _getVariables(library.variables), _getMethods(library.functions),
           _getClasses(library.classes));
-      _writeToFile(getYamlString(result.toMap()), "${result.name}.yaml");
+      if (outputToJson) {
+        _writeToFile(stringify(result.toMap()), "${result.name}.json");
+      } else {
+        _writeToFile(getYamlString(result.toMap()), "${result.name}.yaml");
+      }
     });
    }
   
   /**
    * Returns any documentation comments associated with a mirror with
    * simple markdown converted to html.
    */
   String _getComment(DeclarationMirror mirror) {
     String commentText;
     mirror.metadata.forEach((metadata) {
       if (metadata is CommentInstanceMirror) {
         CommentInstanceMirror comment = metadata;
         if (comment.isDocComment) {
           if (commentText == null) {
             commentText = comment.trimmedText;
           } else {
             commentText = "$commentText ${comment.trimmedText}";
           }
         } 
       }
     });
-    // TODO(tmandel): Resolve links to members in markdown using _currentClass,
-    // _currentMember, and _currentLibrary.
     return commentText == null ? "" : 
-      markdown.markdownToHtml(commentText.trim());
+      markdown.markdownToHtml(commentText.trim(), linkResolver: linkResolver);
+  }
+
+  /**
+   * Converts all [_] references in comments to <code>_</code>.
+   */
+  // TODO(tmandel): Create proper links for [_] style markdown based
+  // on scope once layout of viewer is finished.
+  markdown.Node fixReference(String name, LibraryMirror currentLibrary, 
+      ClassMirror currentClass, MemberMirror currentMember) {
+    return new markdown.Element.text('code', name);
   }
   
   /**
    * Returns a map of [Variable] objects constructed from inputted mirrors.
    */
   Map<String, Variable> _getVariables(Map<String, VariableMirror> mirrorMap) {
     var data = {};
     mirrorMap.forEach((String mirrorName, VariableMirror mirror) {
       _currentMember = mirror;
       data[mirrorName] = new Variable(mirrorName, mirror.isFinal,
@@ skipping 122 matching lines @@
  
   Class(this.name, this.superclass, this.isAbstract, this.isTypedef,
       this.comment, this.interfaces, this.variables, this.methods); 
   
   /// Generates a map describing the [Class] object.
   Map toMap() {
     var classMap = {};
     classMap["name"] = name;
     classMap["comment"] = comment;
     classMap["superclass"] = superclass;
-    classMap["abstract"] = isAbstract;
-    classMap["typedef"] = isTypedef;
-    classMap["implements"] = interfaces;
+    classMap["abstract"] = isAbstract.toString();
+    classMap["typedef"] = isTypedef.toString();
+    classMap["implements"] = new List.from(interfaces);
     classMap["variables"] = recurseMap(variables);
     classMap["methods"] = recurseMap(methods);
     return classMap;
   }
 }
 
 /**
  * A class containing properties of a Dart variable.
  */
 class Variable {
   
   /// Documentation comment with converted markdown.
   String comment;
   
   String name;
   bool isFinal;
   bool isStatic;
   String type;
   
   Variable(this.name, this.isFinal, this.isStatic, this.type, this.comment);
   
   /// Generates a map describing the [Variable] object.
   Map toMap() {
     var variableMap = {};
     variableMap["name"] = name;
     variableMap["comment"] = comment;
-    variableMap["final"] = isFinal;
-    variableMap["static"] = isStatic;
+    variableMap["final"] = isFinal.toString();
+    variableMap["static"] = isStatic.toString();
     variableMap["type"] = type;
     return variableMap;
   }
 }
 
 /**
  * A class containing properties of a Dart method.
  */
 class Method {
   
@@ skipping 13 matching lines @@
   
   Method(this.name, this.isSetter, this.isGetter, this.isConstructor,
       this.isOperator, this.isStatic, this.returnType, this.comment,
       this.parameters);
   
   /// Generates a map describing the [Method] object.
   Map toMap() {
     var methodMap = {};
     methodMap["name"] = name;
     methodMap["comment"] = comment;
-    methodMap["type"] = isSetter ? "Setter" : isGetter ? "Getter" :
-      isOperator ? "Operator" : isConstructor ? "Constructor" : "Method";
-    methodMap["static"] = isStatic;
+    methodMap["type"] = isSetter ? "setter" : isGetter ? "getter" :
+      isOperator ? "operator" : isConstructor ? "constructor" : "method";
+    methodMap["static"] = isStatic.toString();
     methodMap["return"] = returnType;
     methodMap["parameters"] = recurseMap(parameters);
     return methodMap;
   }  
 }
 
 /**
  * A class containing properties of a Dart method/function parameter.
  */
 class Parameter {
   
   String name;
   bool isOptional;
   bool isNamed;
   bool hasDefaultValue;
   String type;
   String defaultValue;
   
   Parameter(this.name, this.isOptional, this.isNamed, this.hasDefaultValue,
       this.type, this.defaultValue);
   
   /// Generates a map describing the [Parameter] object.
   Map toMap() {
     var parameterMap = {};
     parameterMap["name"] = name;
-    parameterMap["optional"] = isOptional;
-    parameterMap["default"] = hasDefaultValue;
+    parameterMap["optional"] = isOptional.toString();
+    parameterMap["named"] = isNamed.toString();
+    parameterMap["default"] = hasDefaultValue.toString();
     parameterMap["type"] = type;
     parameterMap["value"] = defaultValue;
     return parameterMap;
   } 
 }
 
 /**
  * Writes text to a file in the 'docs' directory.
  */
 void _writeToFile(String text, String filename) {
   Directory dir = new Directory('docs');
   if (!dir.existsSync()) {
     dir.createSync();
   }
   File file = new File('docs/$filename');
   if (!file.exists()) {
     file.createSync();
   }
   file.openSync();
   file.writeAsString(text);
 }