mox

A markdown javascript documentation generator

Get Going

var mox = require("mox");

var source = "./source1.js";

mox.run(source1).pipe(process.stdout)
=> //outputs markdown data

##Purpose

This project allows extended flexiblity in generating markdown documentation for javascript projects. The advantage of this project over others is:

• Allows you to easily create a table of contents of methods, declarations, categories, source file names
• Allows you to group your code using the @category tag
• Allows you to group your code using the source file name

It was inspired by the lodash documentation.

Mox generates source documentation based on jsdoc and dox. For information on how to document your source see the following:

• Use JsDoc Reference
• Dox reference

Mox templates use jade as the templating engine. To create custom templates see jade documentation for reference

Install

npm install mox

Example output

See the examples directory for ouput using the predefined mox templates:

examples

How to use

Default Template

var fs = require("fs");
var mox = require("../lib/mox");

var source1 = "./source1.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")


mox.run([source1]).pipe(fileWriteStream);

=> //markdown documentation file will be generated to output directory

Options

All below options are available to mox

var allMoxOptions = {
	name : "someProjectName", //-> name of the project or application being documented

	version : "aVersion", //-> documentation or project version number

	moxFile : "mox object json output file",

	htmlFile : "htmlFile" //-> html generated output file path,

	outputFile : "./someOutputFile.md", //-> mark down documentation output file,

	template : "moxTemplateName | ./someCustomTemplate.jade", //-> mox template name or custom template to use
}

Default Template With Multiple Sources

var fs = require("fs");
var mox = require("../lib/mox");

var source1 = "./source1.js";
var source2 = "./source2.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")


mox.run([source1,source2]).pipe(fileWriteStream);

=> //markdown documentation file will be generated to output directory

Categroy Template

var fs = require("fs");
var mox = require("../lib/mox");

var source1 = "./source1.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")

mox.run(source1,{template:"category"}).pipe(fileWriteStream);
=> //markdown documentation file will be generated to output directory

File Template

var fs = require("fs");
var mox = require("../lib/mox");

var source1 = "./source1.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")

mox.run(source1,{template:"file"}).pipe(fileWriteStream);
=> //markdown documentation file will be generated to output directory

Default Template with Github Flavored Markdown(gfm)

var fs = require("fs");
var mox = require("../lib/mox");

var source1 = "./source1.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")

mox.run(source1,{markdown:"gfm"}).pipe(fileWriteStream);
=> //markdown documentation file will be generated through file stream

Custom Template

A custom template can be created. All templates must be created using jade. See jade documentation for details on how to use jade. The jade template will have access to the mox object.

Sample Custom template(customTemplate.jade)

doctype 5
html
	body
		h2 Application Objects, Functions, Declarations
		ul
			each comment in mox
				li
					a(href="##{comment.name.toLowerCase()}")= comment.name
		h2 Application Objects, Functions, Declarations
		each comment in mox
			h3= comment.name
			p!= comment.description.body

Here is how to use the custom template in mox

var fs = require("fs");
var mox = require("../lib/mox");

var source1 = "./source1.js";
var fileWriteStream = fs.createWriteStream("./someOutputfile.md")

mox.run(source1, //->source files to generate documentation for
		{template:'./customTemplate.jade'}) //->specfies path to custom template
		.pipe(fileWriteStream); 
=> //markdown documentation file will be created to file stream

Default Template with outputfile

var mox = require("../lib/mox");

var source1 = "./source1.js";
var source2 = "./source2.js";
var options = {
	outputFile :"./someOutputfile.md" //->output markdown file
};

mox.run([source1,source2], //->source files to generate documentation for
		options); 
=> //markdown documentation file will be created to output directory

Asynchronus results

Markdown documentation will be returned if a callback is specfied as the last argument

var mox = require("../lib/mox");

var source1 = "./source1.js";
var source2 = "./source2.js";

var options = {
	outputFile :"./someOutputfile.md", //->output markdown file
	template:'category' //-> Using category template
};

mox.run([source1,source2], //->source files to generate documentation for
		options, //-> Mox options
		function(error,markdownDocumentation){}); //->markdownDocumentation equals the markdown file contents
=> //markdown documentation file will be created to output directory

What gets generated

Mox uses dox to generate all documentation comments. All dox comments will be available to use in a template.

Here is the object that gets created and is available to all templates:

{
	mox : moxComments, //-> mox generated comments

	comments : allSourceComments, //-> generated dox comments

	files : files, //-> mox generated comments grouped by source filename
					//-> {tag: "nameOfile",
					//->  comment : **GeneratedMoxCommentObject**}

	categories : categories, //-> mox generated comments grouped by **@categoy** tag
							//-> {tag: "nameOfCategory",
							//->  comment : **GeneratedMoxCommentObject**}
}

Mox generated comments

The mox generated comments are subset of dox comments that allow for grouping and additional data

####Given class

/**
 * A Class description
 *
 * Example:
 * 
 * ```javascript
 * SomeClass.someClassMethod(x);
 * ```
 *
 * @author Tim Chaplin
 * @category SomeClassCategory
 * @class SomeClass
 * @constructor
 * @param {String} param a parameter
 * @optional
 */
function SomeClass(){}

Generates mox object:

[ 
	{ 
		params: [ 
			{
				types: ['Function', 'String'],
				name : "paramName",
				description : "description"
			}],
		name: 'SomeClass',
		type: 'function',
		fileName: 'someFileName.js',
		description: 
			{ 
				full: '<p>A Class description</p>\n\n<p>Example:</p>\n\n<div class="highlight"><pre lang="javascript">SomeClass.	someClassMethod(x);\n</pre></div>',
				summary: '<p>A Class description</p>',
				body: '<p>Example:</p>\n\n<div class="highlight"><pre lang="javascript">SomeClass.someClassMethod(x);\n</pre></div>' 
			},
		author: 'Tim Chaplin',
		category: 'SomeClassCategory',
		class: 'SomeClass',
		constructor: true,
		optional: true
	}
]

####Given Method

function SomeClass(){
	/**
	 * SomeClassFunction
 	 *
 	 * Example:
 	 *
 	 * ```javascript
 	 * SomeClass.someClassMethod(x);
 	 * ```
	 * @category SomeClassCategory
	 * @method someClassMethod
	 * @param {Function|String} methodParam some method param
	 * @return {Function|String} A return value
	 * @chainable
	**/
	self.someClassMethod = function(methodParam) {
		self.lib.Plugins.loadPlugin(self, pluginPath);
		return self;
	};
}

Generates mox object:

[ 
	{ 
		params: { 
			[{
			    types: ['Function', 'String'],
			    name : "paramName",
			    description : "description"
		    }],
		name: 'someClassMethod',
		type: 'method',
		fileName: 'someFileName.js',
		description: 
		{ 
			full: '<p>SomeClassFunction</p>\n\n<p>Example:</p>\n\n<div class="highlight"><pre lang="javascript">SomeClass.someClassMethod(x);\n</pre></div>',
			summary: '<p>SomeClassFunction</p>',
			body: '<p>Example:</p>\n\n<div class="highlight"><pre lang="javascript">SomeClass.someClassMethod(x);\n</pre></div>' 
		},
		category: 'SomeClassCategory',
		method: 'someClassMethod',
		return: { types: [Object], description: 'A return value' },
		chainable: true 
	}
]

####Given Declaration

/** Some property Thing */
var aProperty = "someProperty";

Generates mox object:

[ 
  { 
	params: [],
	name: 'aProperty',
	type: 'declaration',
	fileName: 'someFileName.js',
	description: 
	{ 
		full: '<p>Some property Thing</p>',
		summary: '<p>Some property Thing</p>',
		body: '' 
	} 
   }
]

####Given Property with type

/** 
 * Some property with type description
 * @type {String}
 */
var aPropertyWithType = "somePropertyWithType";

Generates mox object:

{
    "params": [],
    "name": "aPropertyWithType",
    "type": {
        "types": [
            "String"
        ]
    },
    "fileName": "./tests/fixtures/functionSomeClass.js",
    "description": {
        "full": "<p>Some property with type description</p>",
        "summary": "<p>Some property with type description</p>",
        "body": ""
    },
    "category": "SomeClassCategory"
}

##Credits/Other Frameworks

Thanks to the following frameworks used as dependcies for the project

• dox - For getting jsdoc style documention object
• Jade- For templating
• hammerdown - Streaming HTML to markdown

Other markdown javascript documentation projects

• Markdox
• jsdox