How to easily create Github friendly markdown for documented JavaScript functions?
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?
Answer
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: