Document formatters

tmcw · tmcw · commit 77a53bee1a42 · 2016-06-08T12:38:47.000-04:00
diff --git a/lib/output/util/formatters.js b/lib/output/util/formatters.js
@@ -5,22 +5,19 @@ var remark = require('remark'),
   _rerouteLinks = require('./reroute_links'),
   formatType = require('./format_type');
 
+/**
+ * Create a formatter group, given a linker method that resolves
+ * namespaces to URLs
+ *
+ * @param {Function} getHref linker method
+ * @returns {formatters} formatter object
+ */
 module.exports = function (getHref) {
   var rerouteLinks = _rerouteLinks.bind(undefined, getHref);
 
   /**
-   * This helper is exposed in templates as `md` and is useful for showing
-   * Markdown-formatted text as proper HTML.
-   *
-   * @param {Function} getHref a method that transforms namepaths to urls
-   * @param {Object} ast - mdast tree
-   * @returns {string} HTML
-   * @private
-   * @example
-   * var x = remark.parse('## foo');
-   * // in template
-   * // {{ md x }}
-   * // generates <h2>foo</h2>
+   * Formatters are helpers for templates: they handle tricky logic
+   * parts like outputting types and parameters.
    */
   var formatters = {};
 
@@ -41,15 +38,25 @@ module.exports = function (getHref) {
     return param.name + ': ' + formatters.type(param.type).replace(/\n/g, '');
   }
 
+  /**
+   * Convert a remark AST to a string of HTML, rerouting links as necessary
+   * @param {Object} ast remark-compatible AST
+   * @returns {string} HTML
+   */
   formatters.markdown = function (ast) {
     if (ast) {
       return remark().use(html).stringify(rerouteLinks(ast));
     }
   };
 
+  /**
+   * Format a type and convert it to HTML
+   *
+   * @param {Object} type doctrine-format type
+   * @returns {string} HTML
+   */
   formatters.type = function (type) {
-    return formatters.markdown(u('root', formatType(getHref, type)))
-      .replace(/\n/g, '');
+    return formatters.markdown(u('root', formatType(getHref, type))).replace(/\n/g, '');
   };
 
   /**
