How to easily create Github friendly markdown for documented JavaScript functions?
JavascriptGithubMarkdownJsdocJavascript Problem Overview
I want to be able to take JSDoc comments like this anywhere in JavaScript source (even nested down several layers of functions, in a module or even anonymous functions):
/**
* Used to do some important thing that needs doing that works like xyz.
* @param {String} whatever - some string that has some purpose
* @param {Function} callback - a function that needs to be run
* @returns {Boolean} whether or not something happened
*/
function something(whatever, callback) {
...
and have some easy way to produce nice markdown:
##`root.something(whatever,callback)`
Used to do some important thing that needs doing that works like xyz.
*Parameters*
`whatever {String}` some string that has some purpose
`callback {Function}` a function that needs to be run
*Returns*
`{Boolean}` whether or not something happened
Where "root" is the namespace at which that function is reachable. Or if it's an anonymous function or a private function (that for some reason should be in public doco, does that even make sense??), use some other convention to denote that. Maybe
##_private_function_ `something(whatever,callback)`
and
##_anonymous_function_`(whatever,callback)`
It doesn't have to be exactly that format, just something that looks good on Github and makes sense. The ideal tool would be smart enough to be able to take code like Mustache.js and produce good output. And extra good would be if it can handle lots of source files and produce one document as output, or a linked set of documents depending on configuration.
And it would be best if this was done in a way that can be fully and easily included in a git repo so that people don't need to set up a highly specific toolchain to update the doco. Or require a minimal toolchain at least.
Oh, and a pony.
Existing options
JSDoc, plus some kind of HTML -> markdown conversion
JSDoc is pretty good. But I can't seem to make it work well with modules. Or rather, it's a bigger hassle than it ought to be IMHO. I shouldn't need to add an extra tag to name the function. I've tried the @export and @name and still have trouble getting it to show up in the final doc the way I'd want. If someone can point to a JSDoc commented source that has modules in it and is done well, that might help. Update: JSDoc v3 actually seems much better with modules than v2 so this might be a better fit.
Even if I could get JSDoc output like I want, I'd need to convert from HTML to markdown. I can't seem to find a good tool for that, does one exist?
Docdown
I played a bit with Docdown but the fact it's PHP is kind of a nonstarter for me...
YUIDoc, plus conversion
I actually haven't played with YUIDoc but it looks ok. Still, I would need a converter. Does it deal with modules easily and avoid having to supply the function name and export name explicitly?
Dox, plus markdown templates
Dox produces JSON as it's output, so then you'd need to marry that to some good markdown templates, and plus include a template engine to generate the documents. Has anyone put together a set of such templates in a useful fashion?
jGrouse, plus conversion
Runs with ANT. Next...
ScriptDoc...
Does this even exist anymore? Seems to be part of Aptana studio so that would be a nonstarter... Aptana doesn't seem to any info on it. But ScriptDoc.org has some interesting information on crack, if that's helpful...
Pdoc
Pdoc is Ruby based but that toolchain is not uncommon so that's not a huge problem. You can provide your own templates so maybe there are already some good markdown ones. I haven't played with it... is it worthwhile? Are there good markdown templates out there?
Something else?
What else is out there?
Make your own!
After messing around with JSDoc for a few hours trying to make it work how I wanted, I gave up and wrote my own quick and dirty solution in Java for CharFunk, a unicode JavaScript library I've been working on. It works well enough for what I need though it's not close to general purpose yet.
So.....
Is this an unmet need or is it just me?
Javascript Solutions
Solution 1 - Javascript
I use jsdoc-to-markdown..
write documented code:
/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}
get markdown docs:
$ jsdoc2md example/function.js
#protection(cloak, dagger)
a quite wonderful function
**Params**
- cloak `object` - privacy gown
- dagger `object` - security
**Returns**: `survival`
These projects have readme files rendered by jsdoc2md:
Solution 2 - Javascript
markdox can generate markdown documents from javascript code.
Solution 3 - Javascript
jsDox. https://github.com/sutoiku/jsdox Full parse using UglifyJS
Mox. https://github.com/tjchaplin/mox Several ready-to-run examples/templates.
Both handle JSDoc/Dox formats. Both have active development. For me, Mox wins because of the example suite.
Solution 4 - Javascript
OK. After some deliberation with myself, I'd go with DOX + Underscore/Whatever JS templating engine over Node.
Should be pretty simple. You can, possibly, even jam into Grunt or similar and have it ran under a watch task.
Dox is, from what I can recall, is relatively lightweight and has an npm package (IIRC).
UPDATE: I think, after some experience, that I'd like to change my answer to YUIDoc.
Solution 5 - Javascript
I had the need of creating a API documentation out of JSDoc which should be easy to use and also supports modern frontend stacks. Some of the mentioned libraries have issues with JS code transpiled into babeljs therefore you have to transpile your code with comments temporarily just to generate your markdown documentation.
For such use case I found http://documentation.js.org/ quite useful as they have integrated support for BabelJs configurations so it takes care of generating markdown (JSON, HTML) from your JSDocs.
Solution 6 - Javascript
Try using Verb. In the simplest use case Verb will build a readme from a template using data from package.json.
But verb also has advanced features if you need to generate multi-page TOCs, or create custom helpers, etc.
Regarding API documentation, see this example readme generated using code comments from index.js. Click on the headings, those are auto-generated too. Use this built-in helper to generate API docs from whatever file path is specified. You can also use glob patterns to pull in docs from multiple files.
Verb will build a .verb.md without any config. But if you need more, you can use a verbfile.js