diff --git a/package.json b/package.json index 86c3874..d4462a1 100644 --- a/package.json +++ b/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", diff --git a/share/markdown.hbs b/share/markdown.hbs index 412a429..fa284c0 100644 --- a/share/markdown.hbs +++ b/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}} diff --git a/streams/output/markdown.js b/streams/output/markdown.js index ae0ffc1..ec30930 100644 --- a/streams/output/markdown.js +++ b/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)); }); diff --git a/test/fixture/inline-link.input.js b/test/fixture/inline-link.input.js new file mode 100644 index 0000000..5eec0d9 --- /dev/null +++ b/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); +}; diff --git a/test/fixture/inline-link.output.custom.md b/test/fixture/inline-link.output.custom.md new file mode 100644 index 0000000..4446cb1 --- /dev/null +++ b/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 + diff --git a/test/fixture/inline-link.output.json b/test/fixture/inline-link.output.json new file mode 100644 index 0000000..1dad740 --- /dev/null +++ b/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" + } +] \ No newline at end of file diff --git a/test/fixture/inline-link.output.md b/test/fixture/inline-link.output.md new file mode 100644 index 0000000..9015fbd --- /dev/null +++ b/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 +