JavaScript Patterns 2.12 Writing API Docs

javaScript Patterns 2.12 Writing API Docs

Free and open source tools for doc generation:

the JSDoc Toolkit (http://code.google.com/p/jsdoc-toolkit/)

and YUIDoc (http://yuilibrary.com/PRojects/yuidoc).

Process of generating API documentation

• Writing specially formatted code blocks

• Running a tool to parse the code and the comments

• Publishing the results of the tool, which are most often HTML pages

/*** Reverse a string** @param {String} input String to reverse* @return {String} The reversed string*/var reverse = function (input) {     // ...     return output;};

The contents of app.js starts like this:

/*** My Javascript application** @module myapp*/

Then you define a blank object to use as a namespace:

var MYAPP = {};

And then you define an object math_stuff that has two methods: sum() and multi():

/*** A math utility* @namespace MYAPP* @class math_stuff*/MYAPP.math_stuff = {    /**    * Sums two numbers    *    * @method sum    * @param {Number} a First number    * @param {Number} b The second number    * @return {Number} The sum of the two inputs    */    sum: function (a, b) {        return a + b;    },/*** Multiplies two numbers** @method multi* @param {Number} a First number* @param {Number} b The second number* @return {Number} The two inputs multiplied*/    multi: function (a, b) {        return a * b;    }};

@namespace

The global reference that contains your object.

@class

A misnomer (no classes in JavaScript) that is used to mean either an object or a constructor function.

@method

Defines a method in an object and specifies the method name.

@param

Lists the arguments that a function takes. The types of the parameters are in curly braces, followed by the parameter name and its description.

@return

Like @param, only it describes the value returned by the method and has no name.

• @constructor hints that this “class” is actually a constructor function

• @property and @type describe properties of an object

/*** Constructs Person objects* @class Person* @constructor* @namespace MYAPP* @param {String} first First name* @param {String} last Last name*/MYAPP.Person = function (first, last) {    /**    * Name of the person    * @property first_name    * @type String    */    this.first_name = first;    /**    * Last (family) name of the person    * @property last_name    * @type String    */    this.last_name = last;}; /*** Returns the name of the person object** @method getName* @return {String} The name of the person*/MYAPP.Person.prototype.getName = function () {    return this.first_name + ' ' + this.last_name;};

YUIDoc Example