This documentation is a work-in-progress

jsdoc-to-markdown

jsdoc documented source code in, markdown format API documentation out.

Synopsis

write documented code:

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

run a command:

$ jsdoc2md example/src/protection.js

get markdown docs! (in github-flavored-markdown format by default)

<a name="protection"></a>
## protection(cloak, dagger) ⇒ <code>survival</code>
a quite wonderful function

| Param  | Type                | Description  |
| ------ | ------------------- | ------------ |
| cloak  | <code>object</code> | privacy gown |
| dagger | <code>object</code> | security     |

this command achieves the same result:

$ jsdoc-parse example/function.js | dmd

Features

• Insert API documention into a README, or any arbitrary document.
• Customisable to a granular level. If the output doesn't suit you, change it.
• Package your modifications, publish to npm and share with others (e.g. dmd-bitbucket)
• Accepts .js or .html input files (parsing html is experimental - more)
• Extends jsdoc with some new tags (more)
• Use any arbitrary tag, e.g. @fulfil, @reject, @hatredlevel etc.

Example output

Some example output creating using jsdoc2md.

Generated README files

These projects insert jsdoc2md output into a readme template.

Project	Notes
handbrake-js	A module exposing two methods and an inner class. The API docs are inserted into this README template by this command: $ jsdoc2md --template jsdoc2md/README.hbs lib/*.js
array-tools	Very simple module exporting a collection of static methods. Demonstrates use of @typicalname (set to a) and the @category tag to group identifiers in the member-list.
ansi-escape-sequences	Demonstrates usage of @enum {type} (rendered in table format).
file-set	Simple module exporting a class.

Tags

You can see an example of how each jsdoc tag looks when rendered here.

Examples demonstrating various options

To get an idea of the affects the various options have:

• formatting options
  • example-lang
  • module-index-format
  • global-index-format
  • member-index-format
  • param-list-format
  • property-list-format
  • no-gfm
  • separators
  • name format
• parse options
  • html
  • sort-by

Scripting examples

If you can't achieve what you need using the command-line tool you can write a custom script.

• generate one markdown file per class

Templating examples

The default jsdoc2md output might not always suit you. You can supply your using own template using the template option. You can see the template used to generate this README here.

Selectors

• Cherry-pick which documentation appears in the output using selector helpers.
  • {{#module}}
  • {{#class}}

Exemplary APIs

See the wiki for more great API examples. Feel free to add your own!

Install and use

First, document your source code using correct jsdoc syntax then run it through jsdoc-to-markdown using one of the following methods (all tested on Mac OSX, Linux, Windows 8.1 and Windows XP):

Command-line tool

To install the jsdoc2md command-line tool globally, run:

$ npm install -g jsdoc-to-markdown

Some typical use cases:

$ # dump everything you have into a single file
$ jsdoc2md "src/**/*.js" > api.md

$ # split into separate files
$ jsdoc2md src/main-module.js > main-module.md
$ jsdoc2md src/important-class.js > important-class.md

$ # embed documentation into a template you made
$ jsdoc2md "src/**/*.js" --template readme.hbs > README.md

Note on globbing

General rule: if your file expression contains ** yet recursion is failing, wrap the expression in quotes (e.g. "lib/**/*.js").

If wrapped in quotes, bash (or your shell) will not attempt file-name expansion on the expression. If you do not use quotes you will require bash version 4+ with globstar enabled for recursion to work.

Add a "generate docs" task to your project workflow

As an npm run task

This is the most lightweight way to add the task - no additional task-running software required. First:

$ npm install jsdoc-to-markdown --save-dev

Then, in the "scripts" section of package.json, add a docs task. For example:

{
  "scripts": {
    "docs": "jsdoc2md lib/*.js > api.md"
  }
}

Now, project documentation is generated like so:

$ npm run docs

As a grunt task

See grunt-jsdoc-to-markdown.

As a gulp task

See gulp-jsdoc-to-markdown.

Contributing

Issue reports and patches are encouraged. And the project would benefit from an additional maintainer..

Composition

Essentially, jsdoc2d connects the output of jsdoc-parse to the input of dmd. dmd uses the ddata helper library (also shared by dhtml) and stream-handlebars to generate the output.

API Reference

Example

var jsdoc2md = require("jsdoc-to-markdown");

jsdoc2md([options]) ⇒ TransformStream ⏏

Transforms jsdoc into markdown documentation.

Kind: exported function
Params

• [options] DmdOptions | ParseOptions - the options

Example
Two ways to use jsdoc2md. Either pass in filepaths (** glob matching supported) of javascript source files:

> jsdoc2md({ src: "lib/*.js" }).pipe(process.stdout);

or pipe in source code from another source:

> fs.createReadStream("lib/main.js").pipe(jsdoc2md()).pipe(process.stdout);

dmd~DmdOptions

All dmd options and their defaults

Kind: inner class of dmd

• ~DmdOptions
  • .template : string
  • .heading-depth : number
  • .example-lang : string
  • .plugin : array
  • .helper : array
  • .partial : array
  • .name-format : string
  • .no-gfm : boolean
  • .separators : boolean
  • .module-index-format : string
  • .global-index-format : string
  • .param-list-format : string
  • .property-list-format : string
  • .member-index-format : string
  • .group-by : array
  • .locale : object

dmdOptions.template : string

The template the supplied documentation will be rendered into. Use the default or supply your own template for full control over the output.

Kind: instance property of DmdOptions
Default: "{{>main}}"
Example

var fs = require("fs");
var dmd = require("../");

var template = "The description from my class: {{#class name='MyClass'}}{{description}}{{/class}}";

fs.createReadStream(__dirname + "/my-class.json")
    .pipe(dmd({ template: template }))
    .pipe(process.stdout);

outputs:

The description from my class: MyClass is full of wonder

the equivation operation using the command-line tool:

$ dmd --template template.hbs --src my-class.json

dmdOptions.heading-depth : number

The initial heading depth. For example, with a value of 2 the top-level markdown headings look like "## The heading".

Kind: instance property of DmdOptions
Default: 2

dmdOptions.example-lang : string

Specifies the default language used in @example blocks (for syntax-highlighting purposes). In gfm mode, each @example is wrapped in a fenced-code block. Example usage: --example-lang js. Use the special value none for no specific language. While using this option, you can override the supplied language for any @example by specifying the @lang subtag, e.g @example @lang hbs. Specifying @example @lang off will disable code blocks for that example.

Kind: instance property of DmdOptions
Default: "js"

dmdOptions.plugin : array

Use an installed package containing helper and/or partial overrides

Kind: instance property of DmdOptions

dmdOptions.helper : array

handlebars helper files to override or extend the default set

Kind: instance property of DmdOptions

dmdOptions.partial : array

handlebars partial files to override or extend the default set

Kind: instance property of DmdOptions

dmdOptions.name-format : string

Format identifier names in the code style, (i.e. format using backticks or <code></code>)

Kind: instance property of DmdOptions

dmdOptions.no-gfm : boolean

By default, dmd generates github-flavoured markdown. Not all markdown parsers render gfm correctly. If your generated docs look incorrect on sites other than Github (e.g. npmjs.org) try enabling this option to disable Github-specific syntax.

Kind: instance property of DmdOptions

dmdOptions.separators : boolean

Put <hr> breaks between identifiers. Improves readability on bulky docs.

Kind: instance property of DmdOptions
Default: false

dmdOptions.module-index-format : string

none, grouped, table, dl

Kind: instance property of DmdOptions
Default: "dl"

dmdOptions.global-index-format : string

none, grouped, table, dl

Kind: instance property of DmdOptions
Default: "dl"

dmdOptions.param-list-format : string

Two options to render parameter lists: 'list' or 'table' (default). Table format works well in most cases but switch to list if things begin to look crowded / squashed.

Kind: instance property of DmdOptions
Default: "table"

dmdOptions.property-list-format : string

list, table

Kind: instance property of DmdOptions
Default: "table"

dmdOptions.member-index-format : string

grouped, list

Kind: instance property of DmdOptions
Default: "grouped"

dmdOptions.group-by : array

a list of fields to group member indexes by

Kind: instance property of DmdOptions
Default: ["scope","category"]

dmdOptions.locale : object

Overrides the default locale

Kind: instance property of DmdOptions
Default:

jsdocParse~ParseOptions

All options for jsdoc-parse, including defaults

Kind: inner class of jsdocParse

• ~ParseOptions
  • .src : string | Array.<string>
  • .private : boolean
  • .stats : boolean
  • .html : boolean
  • .sort-by : array

parseOptions.src : string | Array.<string>

The source files to parse. If this option is not set jsdoc-parse will wait for input to be streamed in.

Kind: instance property of ParseOptions
Example

var parse = require("jsdoc-parse");
var fs = require("fs");

// either supply one or more file names
parse({ src: "example.js" }).pipe(process.stdout);

// or pipe in source code
fs.createReadStream("example.js").parse().pipe(process.stdout);

parseOptions.private : boolean

Include identifier documentation marked as @private in the output

Kind: instance property of ParseOptions
Default: false

parseOptions.stats : boolean

Print a few stats about the doclets parsed

Kind: instance property of ParseOptions

parseOptions.html : boolean

Enable experimental parsing of .html files.

Kind: instance property of ParseOptions
Default: false

parseOptions.sort-by : array

Sort by one of more fields, e.g. --sort-by kind category.

Kind: instance property of ParseOptions
Default: ["scope","category","kind","order"]

---

© 2015 Lloyd Brookes <[email protected]>. Documented by jsdoc-to-markdown.