72

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?

4
  • 1
    While I am pretty sure this gets closed for whatever is the current reason is - I like DOX and YUIDoc - having the ability to get JSON is pretty huge. JSDoc, at least in its current version is a bit of a hussle, what with all the templates and awkward custom tags creation/usage.
    – ZenMaster
    Mar 29, 2013 at 0:38
  • have you tried github.com/75lb/jsdoc-to-markdown?
    – Lloyd
    Jul 18, 2014 at 23:01
  • So what did you finally choose?
    – Shrike
    Aug 13, 2014 at 16:29
  • what did you use ? Jul 8, 2022 at 12:24

6 Answers 6

28

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:

3
  • best I found so far, but when I used with angular *.component.ts file it didnt work. JSDOC_ERROR: There are no input files to process.;
    – Joey Gough
    Mar 12, 2019 at 12:49
  • @JoeyGough read this: usejsdoc.org/…. You need to specify your input files in the jsdoc config then pass the config file path to jsdoc2md -c
    – Lloyd
    Mar 12, 2019 at 16:43
  • How can you document a callback parameters both with type and name when using JSDoc and jsdoc-to-markdown?
    – tonix
    Apr 18, 2020 at 21:35
7

markdox can generate markdown documents from javascript code.

4

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.

2
  • 1
    Looks like Mox is no longer actively developed (last commit April 2014). Jan 12, 2015 at 23:01
  • @DanDascalescu It may still work though. Not everything needs to be developed forever! :)
    – trusktr
    Aug 17, 2017 at 23:45
2

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.

1
  • Agree with switching to YUI for generating MD. Dox isn't full-fledged yet. Inline linking @link is ignored and also, if source doc is written keeping jsDoc markdown parser in mind, then Dox output is screwed. It treats every new-line in descriptions as a new line for output. Jun 11, 2014 at 18:46
1

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.

0

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

3
  • Does Verb look at JsDoc-like comments in source code to output doc? Cause that's (very clearly if you read my question) what I'm after
    – jwl
    Feb 8, 2015 at 2:09
  • Yes. 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 Feb 9, 2015 at 0:13
  • Your hyperlink points to a GitHub profile, not a repository
    – KaKi87
    Nov 27, 2022 at 14:31

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.