mdast-powered Markdown output

Author: tmcw

docs/THEME_MARKDOWN.md

@@ -10,6 +10,7 @@ var sort = require('./lib/sort'),
   parse = require('./lib/parsers/javascript'),
   polyglot = require('./lib/parsers/polyglot'),
   github = require('./lib/github'),
+  hierarchy = require('./lib/hierarchy'),
   inferName = require('./lib/infer/name'),
   inferKind = require('./lib/infer/kind'),
   inferMembership = require('./lib/infer/membership'),
@@ -20,7 +21,7 @@ var sort = require('./lib/sort'),
  * comments, given a root file as a path.
  *
  * @name documentation
- * @param {Array<String>|String} indexes files to process
+ * @param {Array<string>|string} indexes files to process
  * @param {Object} options options
  * @param {Array<string>} options.external a string regex / glob match pattern
  * that defines what external modules will be whitelisted and included in the
@@ -51,7 +52,7 @@ module.exports = function (indexes, options, callback) {
 
   return inputStream.pipe(concat(function (inputs) {
     try {
-      callback(null, inputs
+      var flat = inputs
         .filter(filterJS)
         .reduce(function (memo, file) {
           return memo.concat(parse(file));
@@ -65,7 +66,8 @@ module.exports = function (indexes, options, callback) {
           return comment;
         })
         .sort(sort.bind(undefined, options.order))
-        .filter(filterAccess.bind(undefined, options.private ? [] : undefined)));
+        .filter(filterAccess.bind(undefined, options.private ? [] : undefined))
+      callback(null, options.hierarchy !== false ? hierarchy(flat) : flat);
     } catch (e) {
       callback(e);
     }

index.js

@@ -19,10 +19,12 @@ var args = require('yargs')
   .describe('name', 'project name. by default, inferred from package.json')
   .describe('version', 'project version. by default, inferred from package.json')
 
-  .boolean('shallow')
-  .describe('shallow', 'shallow mode turns off dependency resolution, ' +
-    'only processing the specified files (or the main script specified in package.json)')
-  .default('shallow', false)
+  .option('shallow', {
+    describe: 'shallow mode turns off dependency resolution, ' +
+    'only processing the specified files (or the main script specified in package.json)',
+    default: false,
+    type: 'boolean'
+  })
 
   .boolean('polyglot')
   .describe('polyglot', 'polyglot mode turns off dependency resolution and ' +
@@ -32,10 +34,12 @@ var args = require('yargs')
   .describe('g', 'infer links to github in documentation')
   .alias('g', 'github')
 
-  .describe('o', 'output location. omit for stdout, otherwise is a filename ' +
-            'for single-file outputs and a directory name for multi-file outputs like html')
-  .alias('o', 'output')
-  .default('o', 'stdout')
+  .option('o', {
+    describe: 'output location. omit for stdout, otherwise is a filename ' +
+      'for single-file outputs and a directory name for multi-file outputs like html',
+    alias: 'output',
+    default: 'stdout'
+  })
 
   .describe('c', 'configuration file. an array defining explicit sort order')
   .alias('c', 'config')

lib/args.js

@@ -7,7 +7,7 @@
  *
  * @name access
  * @public
- * @param {Array<String>} [levels=[private]] excluded access levels.
+ * @param {Array<string>} [levels=[private]] excluded access levels.
  * @param {Object} comment a parsed comment
  * @return {boolean} whether the comment should be output
  */

lib/filter_access.js

@@ -62,14 +62,15 @@ function inferHierarchy(comments) {
       continue;
     }
 
+
     switch (comment.kind) {
     case 'event':
       parent.events.push(comment);
       break;
 
     default:
       if (!comment.scope) {
-        comment.errors.push('found memberof but no @scope, @static, or @instance tag');
+        parent.errors.push('found memberof but no @scope, @static, or @instance tag');
         continue;
       }
       parent.members[comment.scope].push(comment);

lib/hierarchy.js

@@ -2,11 +2,10 @@
 
 var slugg = require('slugg'),
   getGlobalExternalLink = require('globals-docs').getDoc,
-  Remarkable = require('remarkable'),
+  mdast = require('mdast'),
+  html = require('mdast-html'),
   inlineLex = require('jsdoc-inline-lex');
 
-var md = new Remarkable();
-
 /**
  * Make slugg a unary so we can use it in functions
  *
@@ -81,7 +80,7 @@ function autolink(paths, text) {
  * @name formatType
  * @param {Object} type type object in doctrine style
  * @param {Array<string>} paths valid namespace paths that can be linked
- * @returns {String} string
+ * @returns {string} string
  * @example
  * var x = { type: 'NameExpression', name: 'String' };
  * // in template
@@ -104,6 +103,8 @@ function formatType(type, paths) {
   case 'TypeApplication':
     return formatType(type.expression, paths) + '<' +
       type.applications.map(recurse).join(', ') + '>';
+  case 'UndefinedLiteral':
+    return 'undefined';
   }
 }
 
@@ -113,7 +114,7 @@ function formatType(type, paths) {
  * parameters
  *
  * @param {Object} param a param as a type spec
- * @returns {String} formatted parameter representation.
+ * @returns {string} formatted parameter representation.
  */
 function formatParameter(param) {
   return (param.type && param.type.type === 'OptionalType') ?
@@ -157,16 +158,16 @@ module.exports = function (Handlebars, paths) {
    * Markdown-formatted text as proper HTML.
    *
    * @name formatMarkdown
-   * @param {String} string
-   * @returns {String} string
+   * @param {string} string
+   * @returns {string} string
    * @example
    * var x = '## foo';
    * // in template
    * // {{ md x }}
    * // generates <h2>foo</h2>
    */
   Handlebars.registerHelper('md', function formatMarkdown(string) {
-    return new Handlebars.SafeString(md.render(formatInlineTags(string)));
+    return new Handlebars.SafeString(mdast().use(html).process(formatInlineTags(string)));
   });
 
   Handlebars.registerHelper('format_type', function (type) {

lib/html_helpers.js

@@ -28,9 +28,6 @@ module.exports = function (comment) {
     }
 
     function checkCanonical(type) {
-      if (!type) {
-        return;
-      }
       if (type.type === 'NameExpression') {
         nameInvariant(type.name);
       } else if (type.type === 'UnionType') {

lib/lint.js

@@ -1,14 +1,3 @@
-'use strict';
-
-/**
- * Given a type object parsed from JSDoc by Doctrine, generate
- * a string representation appropriate for usage in Markdown.
- *
- * @param {Object} type object with 'type' and optionally 'name'
- * members that defines a parameter, property, return type, or other
- * type expression
- * @return {string} formatted markdown expression of that type.
- */
 function formatType(type) {
   if (!type) {
     return '';
@@ -29,6 +18,8 @@ function formatType(type) {
       type.applications.map(function (application) {
         return formatType(application);
       }).join(', ') + '>';
+  case 'UndefinedLiteral':
+    return 'undefined';
   }
 }
 

lib/markdown_format_type.js

@@ -15,7 +15,7 @@ module.exports = {
    * Create a filter function for use with module-deps, allowing the specified
    * external modules through.
    *
-   * @param {Array<String>} indexes - the list of entry points that will be
+   * @param {Array<string>} indexes - the list of entry points that will be
    * used by module-deps
    * @param {Object} options - An options object with `external` being a
    * micromatch-compaitible glob. *NOTE:* the glob will be matched relative to