Try the jsdoc2md v2 pre-release
jsdoc-to-markdown
jsdoc documented source code in, markdown format API documentation out.
Synopsis
write documented code:
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
|
command-line-args | Demonstrates documentation of ES2015 classes plus the @module , @typicalname , @throws and @alias tags. |
array-tools | Very simple module exporting a collection of static methods. Demonstrates use of @category to group identifiers in the member-list. |
jesucarr/tokenbucket | Demonstrates --param-list-format list and the documentation of Promises using the @fulfil and @reject tags. |
ansi-escape-sequences | Demonstrates usage of @enum {type} (rendered in table format). |
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:
Scripting examples
If you can't achieve what you need using the command-line tool you can write a custom script.
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
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:
$
$ jsdoc2md "src/**/*.js" > api.md
$
$ jsdoc2md src/main-module.js > main-module.md
$ jsdoc2md src/important-class.js > important-class.md
$
$ 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")
Transforms jsdoc into markdown documentation.
Kind: Exported function
Params
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
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"]
jsdocParse~ParseOptions
All options for jsdoc-parse, including defaults
Kind: inner class of jsdocParse
parseOptions.src : string
| Array.<string>
A list of javascript source files (or glob expressions) to parse for documentation. If this option is not set jsdoc-parse will wait for source code on stdin (i.e. cat *.js | jsdoc-parse <options>
).
Kind: instance property of ParseOptions
Example
var parse = require("jsdoc-parse")
var fs = require("fs")
parse({ src: "example.js" }).pipe(process.stdout)
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.conf : boolean
Path to a jsdoc configuration file, passed directly to jsdoc -c
.
Kind: instance property of ParseOptions
parseOptions.sort-by : array
Sort by one of more fields, e.g. --sort-by kind category
. Pass the special value none
to remove the default sort order.
Kind: instance property of ParseOptions
Default: ["scope","category","kind","order"]
© 2014-16 Lloyd Brookes <75pound@gmail.com>. Documented by jsdoc-to-markdown.