DocumentJS  class     

There are several reasons why documentation is important:

• As apps grow, source code becomes complex and difficult to maintain.
• It's beneficial for customers because it helps to educate them on a product.
• Perhaps most importantly, it keeps a project going by bringing new developers up to speed - while also keeping the whole team on the same page.

DocumentJS is a new documentation solution for JavaScript applications. It makes creating, viewing, and maintaining documentation easy and fun. Out of the box, it features:

• Fexible 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 crm 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:

• The example closes comments with *|. You should close them with / instead of |.
• 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 crm 
 * @constructor
 * Creates a new customer.
 * @param {String} name
 */
 var Customer = function(name) {
    this.name = name;
 }

order.js

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

After runnig 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 crm 
 * @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 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 jsonp files (one per type) that are used by the document viewer (jmvcdoc) to render the documentation.

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

Type directives

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

Tag directives

• @alias - another commonly used name for Class or Constructor.
• @author - author of class.
• @codestart -> @codeend - insert highlighted code block.
• @constructor - documents a contructor function and its parameters.
• @demo - placeholder for an application demo.
• @download - adds a download link.
• @iframe - adds an iframe with example code.
• @hide - hide in Class view.
• @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 steald.
• @return - what a function returns.
• @scope - forces the current type to start scope.
• @tag - tags for searching.
• @test - link for test cases.
• @type - sets the type for the current commented code.
• @image - adds an image.

Inspiration

DocumentJS was inspired by the jQuery API Browser by Remy Sharp

DocumentJS(scripts, options)

[{src: "path/to/file.js", text: "var a= 1;"}, { ... }]