Basic formatting for inline links

package.json

@@ -31,6 +31,7 @@
     "handlebars": "^3.0.0",
     "hat": "0.0.3",
     "highlight.js": "^8.4.0",
+    "jsdoc-inline-lex": "^1.0.1",
     "module-deps": "^3.7.3",
     "queue-async": "^1.0.7",
     "remarkable": "^1.6.0",

share/markdown.hbs

@@ -1,14 +1,14 @@
 # `{{name}}`
 
 {{#description}}
-{{.}}
+{{inlines .}}
 {{/description}}
 
 {{#if params}}
 | name | description |
 | ---- | ----------- |
 {{#params}}
-| `{{name}}` | {{description}} |
+| `{{name}}` | {{inlines description}} |
 {{/params}}
 {{/if}}
 
@@ -23,6 +23,6 @@
 {{/if}}
 
 {{#returns}}
-Returns {{#type.name}}`{{.}}`{{/type.name}} {{description}}
+Returns {{#type.name}}`{{.}}`{{/type.name}} {{inlines description}}
 {{/returns}}
 

streams/output/markdown.js

@@ -4,7 +4,32 @@ var through = require('through'),
   fs = require('fs'),
   path = require('path'),
   Handlebars = require('handlebars'),
-  extend = require('extend');
+  extend = require('extend'),
+  inlineLex = require('jsdoc-inline-lex');
+
+/**
+ * Format link & tutorial tags with simple code inline tags.
+ *
+ * @param {string} text input - typically a description
+ * @returns {string} markdown-friendly output
+ * @private
+ * @example
+ * formatInlineTags('{@link Foo}'); // "`Foo`"
+ */
+function formatInlineTags(text) {
+  var output = '';
+  var tokens = inlineLex(text);
+
+  for (var i = 0; i < tokens.length; i++) {
+    if (tokens[i].type === 'text') {
+      output += tokens[i].capture[0];
+    } else {
+      output += '`' + tokens[i].capture[1] + '`';
+    }
+  }
+
+  return output;
+}
 
 /**
  * Create a transform stream that formats documentation as Markdown.
@@ -18,13 +43,19 @@ var through = require('through'),
  * @return {stream.Transform}
  */
 module.exports = function (opts) {
+
   var options = extend({}, {
     template: path.resolve(path.join(__dirname, '../../share/markdown.hbs'))
   }, opts);
+
   var template = Handlebars
     .compile(
       fs.readFileSync(options.template, 'utf8'));
 
+  Handlebars.registerHelper('inlines', function (string) {
+    return new Handlebars.SafeString(formatInlineTags(string));
+  });
+
   return through(function (comment) {
     this.push(template(comment));
   });

test/fixture/inline-link.input.js

@@ -0,0 +1,18 @@
+/**
+ * Adds one to a number
+ * @param {number} a the input
+ * @returns {number} the output
+ */
+function addOne(a) {
+  return a + 1;
+}
+
+/**
+ * This function returns the number one. Internally, this uses
+ * {@link addOne} to do the math.
+ * @param {number} a the input
+ * @returns {number} numberone
+ */
+module.exports = function (a) {
+  return addOne(a);
+};

test/fixture/inline-link.output.custom.md

@@ -0,0 +1,17 @@
+## `addOne`
+
+Adds one to a number
+
+* `a`: the input
+
+Returns `number` the output
+
+## `exports`
+
+This function returns the number one. Internally, this uses
+{@link addOne} to do the math.
+
+* `a`: the input
+
+Returns `number` numberone
+

test/fixture/inline-link.output.json

@@ -0,0 +1,145 @@
+[
+  {
+    "description": "Adds one to a number",
+    "tags": [
+      {
+        "title": "param",
+        "description": "the input",
+        "type": {
+          "type": "NameExpression",
+          "name": "number"
+        },
+        "name": "a"
+      },
+      {
+        "title": "returns",
+        "description": "the output",
+        "type": {
+          "type": "NameExpression",
+          "name": "number"
+        }
+      },
+      {
+        "title": "name",
+        "name": "addOne"
+      },
+      {
+        "title": "kind",
+        "kind": "function"
+      }
+    ],
+    "context": {
+      "loc": {
+        "start": {
+          "line": 6,
+          "column": 0
+        },
+        "end": {
+          "line": 8,
+          "column": 1
+        }
+      },
+      "file": "fixture/inline-link.input.js",
+      "code": "function addOne(a) {\n  return a + 1;\n}\n\n/**\n * This function returns the number one. Internally, this uses\n * {@link addOne} to do the math.\n * @param {number} a the input\n * @returns {number} numberone\n */\nmodule.exports = function (a) {\n  return addOne(a);\n};"
+    },
+    "params": [
+      {
+        "title": "param",
+        "description": "the input",
+        "type": {
+          "type": "NameExpression",
+          "name": "number"
+        },
+        "name": "a"
+      }
+    ],
+    "returns": [
+      {
+        "title": "returns",
+        "description": "the output",
+        "type": {
+          "type": "NameExpression",
+          "name": "number"
+        }
+      }
+    ],
+    "name": "addOne",
+    "kind": "function"
+  },
+  {
+    "description": "This function returns the number one. Internally, this uses\n{@link addOne} to do the math.",
+    "tags": [
+      {
+        "title": "param",
+        "description": "the input",
+        "type": {
+          "type": "NameExpression",
+          "name": "number"
+        },
+        "name": "a"
+      },
+      {
+        "title": "returns",
+        "description": "numberone",
+        "type": {
+          "type": "NameExpression",
+          "name": "number"
+        }
+      },
+      {
+        "title": "name",
+        "name": "exports"
+      },
+      {
+        "title": "kind",
+        "kind": "function"
+      },
+      {
+        "title": "memberof",
+        "description": "module"
+      },
+      {
+        "title": "static"
+      }
+    ],
+    "context": {
+      "loc": {
+        "start": {
+          "line": 16,
+          "column": 0
+        },
+        "end": {
+          "line": 18,
+          "column": 2
+        }
+      },
+      "file": "fixture/inline-link.input.js",
+      "code": "function addOne(a) {\n  return a + 1;\n}\n\n/**\n * This function returns the number one. Internally, this uses\n * {@link addOne} to do the math.\n * @param {number} a the input\n * @returns {number} numberone\n */\nmodule.exports = function (a) {\n  return addOne(a);\n};"
+    },
+    "params": [
+      {
+        "title": "param",
+        "description": "the input",
+        "type": {
+          "type": "NameExpression",
+          "name": "number"
+        },
+        "name": "a"
+      }
+    ],
+    "returns": [
+      {
+        "title": "returns",
+        "description": "numberone",
+        "type": {
+          "type": "NameExpression",
+          "name": "number"
+        }
+      }
+    ],
+    "name": "exports",
+    "kind": "function",
+    "memberof": "module",
+    "scope": "static"
+  }
+]

test/fixture/inline-link.output.md

@@ -0,0 +1,23 @@
+# `addOne`
+
+Adds one to a number
+
+| name | description |
+| ---- | ----------- |
+| `a` | the input |
+
+
+Returns `number` the output
+
+# `exports`
+
+This function returns the number one. Internally, this uses
+`addOne` to do the math.
+
+| name | description |
+| ---- | ----------- |
+| `a` | the input |
+
+
+Returns `number` numberone
+