JSDoc configured

JSDoc is a way to put programmer documentation in Javascript code. It’s in the tradition of Doxygen , Javadoc, and C#’s documentation comments.

And what a sorry tradition that is. Tools for extracting that kind of documentation and making, well, documents from it are just atrocious. (Set me straight in a comment if I’m wrong.)  Sure, the various IDEs use those embedded documentation comments to help provide hints to programmers, and that’s great. But making an actual doc to give to somebody?

What I want is to extract the docs to usable markdown syntax, so they’ll render from within gitlab / github. But noooo. I can have quirky and marginally useful markdown. Or I can have tolerable HTML. (I know all the JSDoc stuff is open source. I hope to tackle this markdown problem sometime.)

For a project, I had the need to get JSDoc to generate a document. I wanted the document to be useful, at least a little bit, for explaining dynamic (event-driven) control of UIs to people who do HTML and CSS. Here’s what I settled on after a lot of messing around.

Use the jsdoc package.  npm install --save-dev jsdoc.

Add the ink-docstrap template package:  npm install --save-dev ink-docstrap.

Add a package to assume that names starting with _ are private, and should not appear in the output. npm install --save-dev jsdoc-autoprivate.

Create a configuration file for Jsdoc.  I put mine at /doc/jsdoc-conf.json. It contains this,

{
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": [
      "jsdoc",
      "closure"
    ]
  },
  "opts": {
    "encoding": "utf8",
    "lenient": false,
    "sort": false
  },
  "source": {
    "includePattern": ".+\\.js(doc|x)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "plugins": [
    "node_modules/jsdoc-autoprivate/autoprivate.js"
  ],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false,
    "sort": false
  }
}

Then, generate decently formatted HTML documentation with this kind of command.

jsdoc --configure doc/jsdoc-conf.json \
      --destination doc/api/agent \
      --template ./node_modules/ink-docstrap/template \
    ./static/js/agent"

This example uses the configuration file I mentioned. It puts the documentation in the named directory. It uses the template I downloaded. And it processes the Javascript files in the directory I mentioned.

It does some stuff I need that was hard to figure out:

• Puts the methods in the documentation in the same order as in my code (not alphabetical order).
• Omits elements with names starting with underscore; those are private. (Notice that it ignores the @private tag, unaccountably).
• Hyperlinks to event handler descriptions reasonably well.