• function

DocumentJS

 

DocumentJS makes it easy to produce beautiful and useful documentation for your JavaScript project.

DocumentJS(folder,[options])

Documents everything in a folder path.

DocumentJS("myproject",{});

will generate "myproject/docs.html" and resources in "myproject/docs/".

Parameters

  1. folder {String}

    The folder location to search for files ending with .js.

  2. options {Object}Optional

    Options that configure the behavior of DocumentJS.

    • markdown {Array<String>}

      An array of folders to look for markdown files in. Defaults to folder.

    • out {String}

      Where to place the docs.html and the docs/ folder. Defaults to folder.

    • index {String}

      The name of the object to be documented. Defaults to folder.

    • static {String}

      The file location of static file overwrites for the content in documentjs/site/defaults/static. The content at static is copied to documentjs/site/static/build where the documentjs/site/static/build/build.js module is stolen. The function it returns is called. That function should copy the production ready files to documentjs/site/static/dist where they will be copied to {out}/static.

    • templates {String}

      The file location of template overrides of documentjs/site/defaults/templates.

      The most common templates to overwrite are:

      • layout.mustache - the page's headers / footers and script tags it loads.
      • docs.mustache - the the content of the page.

DocumentJS(files,[options])

Documents a set of code organized in files.

Parameters

  1. files {Array<Object>}

    The files to document. Each file given should include these options:

    • {String} src The path to the file that contains some code.
    • {String} text The code from the file named in src.
    [{src: "path/to/file.js", text: "var a= 1;"}, { ... }]
  2. options {Object}Optional

    Options that configure the behavior of DocumentJS. These are the same as the options for The other signature.

Features

  • Flexible organization of your documentation
  • An integrated documentation viewer where you can search your API
  • Markdown support
  • An extensible architecture

DocumentJS provides powerful and easy to extend documentation functionality. It's smart enough to guess at things like function names and parameters, but powerful enough to generate JavaScriptMVC's entire website!

Organizing your documentation

Let's use an hypothetical little CRM system as an example of how easy it is to organize your documentation with DocumentJS.

First let's create our CRM documentation home page by creating a folder name crm. Paste this code into a file named crm.js inside crm folder.

/*
 * @page index CRM
 * @tag home
 *
 * ###Little CRM
 *  
 * Our little CRM only has two classes:
 *  
 * * Customer 
 * * Order 
 */

Run the documentjs script to generate the docs:

documentjs/doc.bat crm

This is what you should see when you open crm\docs.html:

There are a few things to notice:

  • We create a link to another class with [Animal here].
  • We used the @page directive to create the crm documentation home page. Don't worry about the @tag directive for now, we'll get back to it later.
  • In all the examples in this walkthrough we use markdown markup instead of html to make the documentation more maintainable and easier to read .

Next we document the two classes that make our little crm system. Paste each snippet of code into two files with names customer.js and order.js:

customer.js

/*
 * @class Customer
 * @parent index
 * @constructor
 * Creates a new customer.
 * @param {String} name
 */
 var Customer = function(name) {
    this.name = name;
 }

order.js

/*
 * @class Order
 * @parent index
 * @constructor
 * Creates a new order.
 * @param {String} id
 */
 var Order = function(id) {
    this.id = id;
 }

After running the documentjs script once again you should be able to see this:

We want to be able to both look for our customer's orders and dispatch them so let's add a findById method to our Order class and a dispatch method to our Order's prototype:

order.js

/*  
 * @class Order 
 * @parent index 
 * @constructor
 * Creates a new order.
 * @param {String} id
 */
var Order = function(id) {
    this.id = id;
}

$.extend(Order,
/*
* @static
*/
{
   /*
    * Finds an order by id.
    * @param {String} id Order identification number.
    * @param {Date} [date] Filter order search by this date.
    */
    findById: function(id, date) {

    }
 });

$.extend(Order.prototype,
/*
 * @prototype
 */
 {
    /*
     * Dispatch an order.
     * @return {Boolean} Returns true if order dispatched successfully.
     */
     dispatch: function() {

     }
});

Go ahead and produce the docs by running the documentjs script. You should see your Order methods organized by static and protoype categories.

There's one last thing we need to cover - customizing the document viewer template. The default viewer template file name is summary.ejs and it's located in documentjs/jmvcdoc/summary.ejs. You can use a customized template by copying summary.ejs into the crm folder and changing it according to your needs. Let's try changing the navigation menu core item to crm:

<li class="ui-menu-item">
    <a class="menuLink" href="#&search=crm"><span class="menuSpan">CRM</span></a>
</li>

Remember the @tag directive? We can now change it in our examples from core to crm. You will notice that our crm page will show up every time you click the CRM menu item or type crm in the documentation viewer search box.

If you need for DocumentJS not to document a particular script you can do that by adding the @document-ignore directive to the top of the file.

As you see DocumentJS makes it super easy and fun to organize your documentation!

How DocumentJS works

DocumentJS architecture is organized around the concepts of [DocumentJS.types types] and tags. Types are meant to represent every JavaScript construct you might want to comment like classes, functions and attributes. Tags add aditional information to the comments of the type being processed.

DocumentJS works by loading a set of JavaScript files, then by spliting each file into type/comments pairs and finally parsing each type's comments tag directives to produce a set of html files (one per type) that are used by the document viewer (jmvcdoc) to render the documentation.

DocumentJS was written thinking of extensibility, so it's very easy to add custom type/tag directives to handle your specific documentation needs.

DocumentJS currently requires Steal to be included on the pages you are documenting.

Type directives

  • @add - add docs to a class or constructor described in another file.
  • @constructor - document a class or constructor.
  • @function - document functions.
  • @page - add a standalone page.
  • @property - document values on an object.
  • @prototype - add to the previous class or constructor's prototype functions.
  • @static - add to the previous class or constructor's static functions.

Tag directives

  • @alias - another commonly used name for Class or Constructor.
  • @author - author of class.
  • @codestart and @codeend - insert highlighted code block.
  • @constructor - documents a contructor function and its parameters.
  • @demo - placeholder for an application demo.
  • @download - adds a download link.
  • @hide - hide in Class view.
  • @iframe - adds an iframe with example code.
  • @image - adds an image.
  • @inherits - what the Class or Constructor inherits.
  • @parent - says under which parent the current type should be located.
  • @param - A function's parameter.
  • @plugin - by which plugin this object gets steal'd.
  • @release - specifies the release.
  • @return - what a function returns.
  • @tag - tags for searching.
  • @test - link for test cases.
  • @typedef - aliases a complex type for use in other documentation.

Inspiration

DocumentJS was inspired by the jQuery API Browser by Remy Sharp