doxdown

doxdown is a jsDoc to MkDocs markdown generator. It allows you to control your documentation on a comment by comment basis, choosing the page and document the comment belongs to. This is especially useful when you need to document an API separate to the rest of your codebase.

Running it on a directory with the default options will parse all nested JavaScript files and output a ./doxdown folder. Inside will be a folder for each document with Markdown files and a mkdocs.yml file in the format expected by MkDocs. You can then run MkDocs on any of those folders to build a site that you can deploy to a server.

Installation

The easiest way to get doxdown is with NPM: npm install doxdown --global

Usage / Options

Use the command doxdown with the following options to generate your docs:

Name	Alias	Default	Description
ignore	i	.git,node_modules	comma-separated list of files/directories to ignore
out	o	./doxdown	relative path to the output directory
regex	r	\.js$	regex string for matching files in the source directory
src	s	./	relative path to the source directory

Comment Format

doxdown looks for jsDoc-style comments with a special @docs tag in the format document [// page] // section which describes where the comment belongs in which document. Use a jsDoc @desc to describe the function or event in the format @name - description. You can have any number of @params or @data tags and one @returns tag.

/**
 * @docs Some Docs // Users & Accounts // User Helpers
 * @desc getUsernames - A description of getUsernames
 * @param {Object[]} users - An array of user objects
 * @param {String} users[].name - A user's name
 * @param {Number} limit - The max number to return
 * @returns {String[]} An array of usernames
 */
 
function getUsernames (users, limit) {
    
    const usernames = [];
    
    for (let i = 0; i < limit; i++) {
        usernames.push(users[i].name);
    }
    
    return usernames;
}
 
/**
 * @docs Tracking // Registration
 * @desc registration-complete - Fires when a user successfully completes registration.
 * @data {String} forename - The user's forename
 * @data {String} surname - The user's surname
 * @data {Date} dob - The user's date of birth
 * @data {Object} address - An object containing details of a user's address
 * @data {String} address.house - The house name/no. of the user's address
 * @data {String} address.postcode - The postcode of the user's address
 */
 
SomeTrackingAPI.trigger('registration-complete', {
    forename: "Sherlock",
    surname: "Holmes"
    dob: dateOfBirth,
    address: {
        house: "221B",
        postcode: "NW16XE"
    }
});
 

TODO

• Replace regex option with glob pattern for matching files and directories.