首页 > 代码库 > 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
