javaScript Patterns 2.12 Writing API Docs 2014-05-26 13:57 by 小郝（Kaibo Hao）, ... 阅读, ... 评论, 收藏, 编辑 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