JSPM

work in progress, unstable, draft documentation

#jsdoc-to-markdown jsdoc documented source code in, markdown out.

Essentially, this app connects the output of jsdoc-parse to the input of dmd.

##Synopsis 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 commands achieve the same result:

$ cat example/function.js | jsdoc2md
$ cat example/function.js | jsdoc-parse | dmd
$ jsdoc-parse example/function.js | dmd

##Examples These projects have readme files rendered by jsdoc2md:

• handbrake-js (exports an object with inner class)
• array-tools (exports a object)
• file-set (exports a class)
• command-line-args (exports a class)

##Usage Document your source code using correct jsdoc syntax, then run it through jsdoc2md.

warning: when piping concatenated source code files into jsdoc2md (with a command like $ cat *.js | jsdoc2md the input will be treated as a single file by the jsdoc parser.. this is not always what you want, especially when the input contains multiple @modules.. Use this method of input only for casual testing / checking / manipulation.

The @module tag marks the current file as being its own module. All symbols in the file are assumed to be members of the module unless documented otherwise.

###Command-line tool Install jsdoc2md globally:

$ npm install -g jsdoc-to-markdown

Options:

$ jsdoc2md -h

  jsdoc-to-markdown
  Markdown API documentation generator, good for Github projects

  Usage
  $ jsdoc2md [<options>] <source_files>
  $ cat <source_files> | jsdoc2md [<options>]

  --src <array>             A list of javascript source files or glob expressions
  -t, --template <string>   A custom handlebars template to insert the rendered documentation into
  -j, --json                Output the parsed jsdoc data only
  -v, --verbose             More verbose error reporting
  -h, --help                Print usage information
  --private                 Include symbols marked @private in the output
  -s, --stats               Print a few stats about the doclets parsed.
  --heading-depth <number>  root heading depth to begin the documentation from, defaults to 1 (`#`).
  -p, --plugin <array>      Use an installed package containing helper and/or partial overrides
  --helper <array>          handlebars helper files to override or extend the default set
  --partial <array>         handlebars partial files to override or extend the default set

Some typical use cases:

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

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

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

###Bundled with your project ####As an npm run task

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

Then add a docs build script to your package.json, e.g.:

{
  "name": "my-web-app",
  "version": "1.0.0",
  "scripts": {
    "docs": "jsdoc2md lib/*.js > api.md"
  }
}

Docs are generated like so:

$ npm run docs

####As a grunt plug-in See grunt-jsdoc-to-markdown.

####As a gulp plug-in Use a task like this until the gulp plugin is ready, you should only need to edit src and outputFile:

var jsdoc2md = require("jsdoc-to-markdown");
var gutil = require("gulp-util");
var fs = require("fs");

gulp.task("docs", function(done){
    var src = "lib/**/*.js";
    var outputFile = "api.md";
    gutil.log("writing documentation to " + outputFile);
    jsdoc2md.render(src).pipe(fs.createWriteStream(outputFile));
});

###Library Example

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

####jsdoc2md.render(src, options) Transforms jsdoc into markdown documentation.

Params

• src string | Array.<string> - The javascript source file(s).
• options object - The render options
  • [template] string - A custom handlebars template to insert the rendered documentation into.
  • [json] boolean - Output the parsed jsdoc data only
  • [private] boolean - Include symbols marked @private in the output
  • [stats] boolean - Print a few stats about the doclets parsed
  • [heading-depth] number - root heading depth, defaults to 1 (#)
  • [plugin] string | Array.<string> - Use an installed package containing helper and/or partial overrides
  • [helper] string | Array.<string> - handlebars helper files to override or extend the default set
  • [partial] string | Array.<string> - handlebars partial files to override or extend the default set

Returns: stream - A transform stream containing the rendered markdown
Example
Two ways to use render. Either pass in filepaths (** glob matching supported) of javascript source files:

> jsdoc2md.render("lib/*.js").pipe(process.stdout);

or pipe in source code from another source:

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

output looks something like:

generates:
```markdown
#jsdoc-to-markdown
**Members**
[jsdoc2md.render(sourceFiles, options)](#module_jsdoc-to-markdown.render)
[jsdoc2md.createRenderStream(options)](#module_jsdoc-to-markdown.createRenderStream)

<a name="module_jsdoc-to-markdown.render"></a>
##jsdoc2md.render(sourceFiles, options)
Renders the jsdoc documentation from the specified source files as markdown.
**Params**

- sourceFiles `string` | `Array.<string>` - The javascript source file(s) - required.
- options `object` - The render options
  - [template] `string` - A handlebars template to insert your documentation into.
  - [json] `boolean` - Return the JSON template data only
  - [stats] `boolean` - Return a few stats about the doclets parsed
  - [private] `boolean` - Include symbols marked @private in the output
  - [heading-depth] `number` - Root heading depth, defaults to 1.
**Returns**: `stream` - A readable stream containing the rendered markdown

etc.
etc.