Document the Javascript API — JSDoc

[nfreear]

HI @timcoughlan,

I have a long-term proposal ... add annotated comments to the Javascript to generate API documentation in a HTML mini-site — see: usejsdoc.org. The idea and the annotation syntax grew out of JavaDocs.

An example:

src/config.js:

/**
 * The default configuration.
 *
 * @namespace DEFAULTS
 * @prop {string} containerSelector  A CSS-style selector for the containing HTML element.
 */
const DEFAULTS = {
  containerSelector: '#our-journey-tool'

  // Other options ...
};

There will be a configuration file, and an npm script :- npm run jsdoc. Documentation will appear in a ./jsdoc/ directory.

Obvious things to start documenting — we start as small as we like ;):

1. src/config.js — Defaults and configuration options;
2. src/app.js — The run() function;
3. index.js — The top-level API;

Ta,

Nick

---

Note: while the annotated comments will bulk out dist/our-journey.js they are stripped from the minified dist/our-journey.min.js.

Audience for the JSDocs:

1. Developers wishing to use and extend;
2. Developers wishing to contribute.