jsdoc-to-markdown/docs/API.md

jsdoc-to-markdown

Example

const jsdoc2md = require('jsdoc-to-markdown')

• jsdoc-to-markdown
  • .clear() ⇒ Promise
  • async
    • .render([options]) ⇒ Promise
    • .getTemplateData([options]) ⇒ Promise
  • sync
    • .renderSync([options]) ⇒ string
    • .getTemplateDataSync([options]) ⇒

jsdoc2md.clear() ⇒ Promise

Clear the cache.

Kind: static method of jsdoc-to-markdown

jsdoc2md.render([options]) ⇒ Promise

Returns markdown documentation from jsdoc-annoted source code.

Kind: static method of jsdoc-to-markdown
Category: async
Fulfil: string - the rendered docs

Param	Type	Description
[options]	object	the options

Example
Pass in filepaths (** glob matching supported) of javascript source files:

> jsdoc2md.render('lib/*.js').then(console.log)

jsdoc2md.getTemplateData([options]) ⇒ Promise

Returns template data (jsdoc-parse output).

Kind: static method of jsdoc-to-markdown
Category: async
Fulfil: object[] - the json data

Param	Type	Description
[options]	object	the options

jsdoc2md.renderSync([options]) ⇒ string

Returns markdown documentation from jsdoc-annoted source code.

Kind: static method of jsdoc-to-markdown
Category: sync
Engine: nodejs >= 0.12

Param	Type	Description
[options]	object	the options

Example

const docs = jsdoc2md.renderSync('lib/*.js')

jsdoc2md.getTemplateDataSync([options]) ⇒

Returns template data (jsdoc-parse output).

Kind: static method of jsdoc-to-markdown
Returns: {object[]
Category: sync

Param	Type	Description
[options]	object	the options

jsdoc~JsdocOptions

The jsdoc options, common for all operations.

Kind: inner class of jsdoc-api

• ~JsdocOptions
  • .files : string | Array.<string>
  • .source : string
  • .cache : boolean
  • .access : string
  • .configure : string
  • .destination : string
  • .encoding : string
  • .private : boolean
  • .package : string
  • .pedantic : boolean
  • .query : string
  • .recurse : boolean
  • .readme : string
  • .template : string
  • .tutorials : string
  • .html : boolean

options.files : string | Array.<string>

One or more filenames to process. Either this or source must be supplied.

Kind: instance property of JsdocOptions

options.source : string

A string containing source code to process. Either this or source must be supplied.

Kind: instance property of JsdocOptions

options.cache : boolean

Set to true to cache the output - future invocations with the same input will return immediately.

Kind: instance property of JsdocOptions

options.access : string

Only display symbols with the given access: "public", "protected", "private" or "undefined", or "all" for all access levels. Default: all except "private".

Kind: instance property of JsdocOptions

options.configure : string

The path to the configuration file. Default: path/to/jsdoc/conf.json.

Kind: instance property of JsdocOptions

options.destination : string

The path to the output folder. Use "console" to dump data to the console. Default: ./out/.

Kind: instance property of JsdocOptions

options.encoding : string

Assume this encoding when reading all source files. Default: utf8.

Kind: instance property of JsdocOptions

options.private : boolean

Display symbols marked with the @private tag. Equivalent to "--access all". Default: false.

Kind: instance property of JsdocOptions

options.package : string

The path to the project's package file. Default: path/to/sourcefiles/package.json

Kind: instance property of JsdocOptions

options.pedantic : boolean

Treat errors as fatal errors, and treat warnings as errors. Default: false.

Kind: instance property of JsdocOptions

options.query : string

A query string to parse and store in jsdoc.env.opts.query. Example: foo=bar&baz=true.

Kind: instance property of JsdocOptions

options.recurse : boolean

Recurse into subdirectories when scanning for source files and tutorials.

Kind: instance property of JsdocOptions

options.readme : string

The path to the project's README file. Default: path/to/sourcefiles/README.md.

Kind: instance property of JsdocOptions

options.template : string

The path to the template to use. Default: path/to/jsdoc/templates/default.

Kind: instance property of JsdocOptions

options.tutorials : string

Directory in which JSDoc should search for tutorials.

Kind: instance property of JsdocOptions

options.html : boolean

Enable experimental parsing of .html files.

Kind: instance property of JsdocOptions

jsdoc~JsdocOptions

The jsdoc options, common for all operations.

Kind: inner class of jsdoc-api

• ~JsdocOptions
  • .files : string | Array.<string>
  • .source : string
  • .cache : boolean
  • .access : string
  • .configure : string
  • .destination : string
  • .encoding : string
  • .private : boolean
  • .package : string
  • .pedantic : boolean
  • .query : string
  • .recurse : boolean
  • .readme : string
  • .template : string
  • .tutorials : string
  • .html : boolean

options.files : string | Array.<string>

One or more filenames to process. Either this or source must be supplied.

Kind: instance property of JsdocOptions

options.source : string

A string containing source code to process. Either this or source must be supplied.

Kind: instance property of JsdocOptions

options.cache : boolean

Set to true to cache the output - future invocations with the same input will return immediately.

Kind: instance property of JsdocOptions

options.access : string

Only display symbols with the given access: "public", "protected", "private" or "undefined", or "all" for all access levels. Default: all except "private".

Kind: instance property of JsdocOptions

options.configure : string

The path to the configuration file. Default: path/to/jsdoc/conf.json.

Kind: instance property of JsdocOptions

options.destination : string

The path to the output folder. Use "console" to dump data to the console. Default: ./out/.

Kind: instance property of JsdocOptions

options.encoding : string

Assume this encoding when reading all source files. Default: utf8.

Kind: instance property of JsdocOptions

options.private : boolean

Display symbols marked with the @private tag. Equivalent to "--access all". Default: false.

Kind: instance property of JsdocOptions

options.package : string

The path to the project's package file. Default: path/to/sourcefiles/package.json

Kind: instance property of JsdocOptions

options.pedantic : boolean

Treat errors as fatal errors, and treat warnings as errors. Default: false.

Kind: instance property of JsdocOptions

options.query : string

A query string to parse and store in jsdoc.env.opts.query. Example: foo=bar&baz=true.

Kind: instance property of JsdocOptions

options.recurse : boolean

Recurse into subdirectories when scanning for source files and tutorials.

Kind: instance property of JsdocOptions

options.readme : string

The path to the project's README file. Default: path/to/sourcefiles/README.md.

Kind: instance property of JsdocOptions

options.template : string

The path to the template to use. Default: path/to/jsdoc/templates/default.

Kind: instance property of JsdocOptions

options.tutorials : string

Directory in which JSDoc should search for tutorials.

Kind: instance property of JsdocOptions

options.html : boolean

Enable experimental parsing of .html files.

Kind: instance property of JsdocOptions

DmdOptions ⏏

All dmd options and their defaults

Kind: Exported class

• 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

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"]