Refactor Markdown AST representation. Fixes #216

Author: tmcw

lib/output/markdown.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var mdast = require('mdast'),
+  toc = require('mdast-toc'),
   markdownAST = require('./markdown_ast');
 
 /**
@@ -14,7 +15,9 @@ var mdast = require('mdast'),
  * @return {undefined} calls callback
  */
 module.exports = function (comments, opts, callback) {
+  var processor = mdast().use(toc);
   markdownAST(comments, opts, function (err, ast) {
-    return callback(null, mdast.stringify(ast));
+    var processedAST = processor.run(ast);
+    return callback(null, processor.stringify(processedAST));
   });
 };

lib/output/markdown_ast.js

@@ -45,14 +45,14 @@ function commentsToAST(comments, opts, callback) {
     }
 
     function paramSection(comment) {
-      return !!comment.params && u('root', [
+      return !!comment.params && [
         u('strong', [u('text', 'Parameters')]),
         paramList(comment.params)
-      ]);
+      ];
     }
 
     function propertySection(comment) {
-      return !!comment.properties && u('root', [
+      return !!comment.properties && [
         u('strong', [u('text', 'Properties')]),
         u('list', { ordered: false },
           comment.properties.map(function (property) {
@@ -66,46 +66,47 @@ function commentsToAST(comments, opts, callback) {
               ])
             ].filter(Boolean))
           }))
-      ]);
+      ];
     }
 
     function examplesSection(comment) {
-      return !!comment.examples && u('root', [
-        u('strong', [u('text', 'Examples')]),
-        u('root', comment.examples.map(function (example) {
+      return !!comment.examples && [u('strong', [u('text', 'Examples')])]
+        .concat(comment.examples.map(function (example) {
           return u('code', { lang: 'javascript' }, example);
-        }))
-      ]);
+        }));
     }
 
     function returnsSection(comment) {
-      return !!comment.returns && u('root', comment.returns.map(function (returns) {
+      return !!comment.returns && comment.returns.map(function (returns) {
         return u('paragraph', [
           u('text', 'Returns '),
           u('strong', [u('text', formatType(returns.type))]),
           u('text', ' '),
           mdast.parse(formatInlineTags(returns.description))
         ]);
-      }));
+      });
     }
 
-    return u('root', [
-      u('heading', { depth: depth }, [u('text', comment.name)]),
-      mdast.parse(formatInlineTags(comment.description)),
-      paramSection(comment),
-      propertySection(comment),
-      examplesSection(comment),
-      returnsSection(comment),
-      !!comment.members.instance.length &&
-        u('root', comment.members.instance.map(generate.bind(null, depth + 1))),
-      !!comment.members.static.length &&
-        u('root', comment.members.static.map(generate.bind(null, depth + 1)))
-    ].filter(Boolean));
+    return [u('heading', { depth: depth }, [u('text', comment.name)])]
+    .concat(mdast.parse(formatInlineTags(comment.description)).children[0])
+    .concat(paramSection(comment))
+    .concat(propertySection(comment))
+    .concat(examplesSection(comment))
+    .concat(returnsSection(comment))
+    .concat(!!comment.members.instance.length &&
+      comment.members.instance.reduce(function (memo, child) {
+        return memo.concat(generate(depth + 1, child));
+      }, []))
+    .concat(!!comment.members.static.length &&
+      comment.members.static.reduce(function (memo, child) {
+        return memo.concat(generate(depth + 1, child));
+      }, []))
+    .filter(Boolean);
   }
 
-  return callback(null, u('root', comments.map(function (comment) {
-    return generate(1, comment);
-  })));
+  return callback(null, u('root', comments.reduce(function (memo, comment) {
+    return memo.concat(generate(1, comment));
+  }, [])));
 }
 
 module.exports = commentsToAST;

test/fixture/class.output.custom.md

@@ -2,37 +2,26 @@
 
 This is my class, a demo thing.
 
-
 **Properties**
 
 -   `howMany`  how many things it contains
 
 
-
 ## getFoo
 
 Get the number 42
 
-
 **Parameters**
 
 -   `getIt` **boolean** whether to get the number
 
 
-
 Returns **number** forty-two
 
 
-
-
 ## getUndefined
 
 Get undefined
 
-
 Returns **undefined** does not return anything.
 
-
-
-
-

test/fixture/class.output.md

@@ -2,37 +2,26 @@
 
 This is my class, a demo thing.
 
-
 **Properties**
 
 -   `howMany`  how many things it contains
 
 
-
 ## getFoo
 
 Get the number 42
 
-
 **Parameters**
 
 -   `getIt` **boolean** whether to get the number
 
 
-
 Returns **number** forty-two
 
 
-
-
 ## getUndefined
 
 Get undefined
 
-
 Returns **undefined** does not return anything.
 
-
-
-
-