jsdox is a simple jsdoc 3 generator. It pulls documentation tags based on a subset of jsdoc 3 from your javascript files and generates markdown files.

Install

$ npm install -g jsdox

jsdox currently relies on (at least for now) a patched version of the UglifyJS parser to get the full javascript AST including comments.

Run

Runs on a single file and outputs the markdown files into the “output” folder

$ jsdox file1.js

Runs on all the files inside folder and outputs the markdown files into the “docs” folder

$ jsdox --output docs folder

Run the tests

Runs jshint and the few tests available under the test folder

$ ./run-tests.sh

API

To call the main jsdox function, use the following code:

jsdox = require("jsdox");

jsdox.generateForDir(input, output, templateDir, cb, fileCb);

input is either a single file (name ends in “.js”), or a folder (one level only) that contains .js files. Files with other extensions will be ignored
output is the destination folder
templateDir is the location of the mustache templates to use
function cb is required and will be called when generation is complete.
function fileCb is optional and will be called for each file with the file and the result of analyze for that file

Tags

jsdox only supports a subset of the the jsdoc 3 set. Here’s the list of what is currently supported (it will safely ignore any tags it does not recognize).

@author text

Specifies the author name, contact information, etc…

@author Joe Schmo

@class name

Documents the classname (usually above the contructor function), subsequent @methods will be gathered as part of this class.

@class  Object

@copyright text

Specify the copyright information with this tag.

@copyright (c) 2012 Blah Blah Blah

@function name

In the case where the function name can not be inferred by jsdox, make it explicit with this tag.

@function testAnonynous

@license text

Specify the license type.

@license MIT

@member [type] name [description]

For a class, defines an object property, with its optional type and a description of what it is used for.

@member {Sheet}  datasheet     The object's 'Data' sheet

@method name

Specify the method name with this tag.

@method create

@module name

All functions, classes or methods after @module will be grouped under this module.

@module test_module

@overview text

Goes into the short description (the overview) at the top of the page under the title.

@overview This is the overview with some `markdown` included, how nice!

@param [type] name [description]

Documents a function or method parameter, with an optional type and optional description.

@param {Boolean} [optional] Changes behavior

@returns [{type}] text

In functions or methods, specify what gets returned and the type of the value returned.

@returns {String} the result

@return

See @returns

@title text

Will be used as the title of the generated page.

@title Some smart title goes here

Examples

Sample output of running jsdox on https://github.com/sutoiku/jsdox/tree/master/fixtures files.

jsdox fixtures --output sample_output

Resources

jsdox Documentation
Github repo
Issue tracker
Contribute by creating pull requests!
Run the test suite using npm test

grunt-jsdox A grunt task to run jsdox on your project

Author and contributors

Pascal Belloncle (psq, Original author)
Sam Blowes (blowsie)
Todd Henderson (thenderson21)
Nic Jansma (nicjansma)
Joel Kemp (mrjoelkemp)
Ron Korving (ronkorving)
Mike MacMillan (mmacmillan)
Marc Trudel (stelcheck)

License

jsdox.js is freely distributable under the terms of the MIT license.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

node.js jsdoc to markdown generator