用JSDoc建立有益的JavaScript相关文档

试用
安装所有必要的组件后，我们就可以尝试使用JSDoc创建文档了。要完成这个任务，我使用列表A中的JavaScript代码。

列表A——样本JavaScript代码

<!-- <![CDATA[

/**

 * @fileoverview This file contains the information necessary to add client-side

 * keyboard restriction functionality to a web page.

 */

/**

 * Accept 'Y' or 'N' and return issue an error message.

 * @requires keybEdit

 */

var keybYN = new keybEdit('yn','Valid values are 'Y' or 'N'.');

/**

 * Accept numeric input and return issue an error message.

 * @requires keybEdit

 */

var keybNumeric = new keybEdit('01234567890','Numeric input only.');

/**

 * Accept numeric input and return issue an error message.

 * @requires keybEdit

 */

var keybAlpha = new keybEdit('abcdefghijklmnopqurstuvwxyz','Alpha input only.');

/**

 * Accept alphabetic input and return issue an error message.

 * @requires keybEdit

 */

var keybAlphaNumeric = new keybEdit('abcdefghijklmnopqurstuvwxyz01234567890/ -,.=!@#$%^&*()_+'":;','Alpha-numeric input only.');

/**

 * Accept alphabetic or numeric input and return issue an error message.

 * @requires keybEdit

 */

var keybDecimal = new keybEdit('01234567890.','Decimal input only.');

/**

 * Accept decimal input and return issue an error message.

 * @requires keybEdit

 */

var keybDate =  new keybEdit('01234567890/','Date input only');;

/**

 * Accept date input and return issue an error message.

 * @requires keybEdit

 */

var keybYNNM = new keybEdit('yn','');

/**

 * Accept numeric input.

 * @requires keybEdit

 */

var keybNumericNM = new keybEdit('01234567890','');

/**

 * Accept alphabetic input.

 * @requires keybEdit

 */

var keybAlphaNM = new keybEdit('abcdefghijklmnopqurstuvwxyz','');

/**

 * Accept alphabetic or numeric input.

 * @requires keybEdit

 */

var keybAlphaNumericNM = new keybEdit('abcdefghijklmnopqurstuvwxyz01234567890/ -,.=!@#$%^&*()_+'":;','');

/**

 * Accept decimal input.

 * @requires keybEdit

 */

var keybDecimalNM = new keybEdit('01234567890.','');

/**

 * Accept date input.

 * @requires keybEdit

 */

var keybDateNM =  new keybEdit('01234567890/','');;

/**

 * keybEdit

 * @class The purpose of this function is to be a constructor for the keybEdit

 * object. keybEdit objects are used by the function editKeyBoard to

 * determine which keystrokes are valid for form objects. In addition, if an

 * error occurs, they provide the error message.

 * @constructor

 * @param {string} strValid Valid input characters

 * @param {string} strMsg Error message

 */

function keybEdit(strValid, strMsg) {

      //    Variables

      var reWork = new RegExp('[a-z]','gi');       //    Regular expression

      //    Properties

      if(reWork.test(strValid))

             this.valid = strValid.toLowerCase() + strValid.toUpperCase();

      else

             this.valid = strValid;

      if((strMsg == null) || (typeof(strMsg) == 'undefined'))

             this.message = '';

      else

             this.message = strMsg;

      /**

       * @ignore

       */

      this.getValid = keybEditGetValid;

      /**

       * @ignore

       */

      this.getMessage = keybEditGetMessage;

      /**

       * Return a boolean indicating whether or not a key stroke is valid.

       * @method getValid

       * @return string-boolean Indicates whether or not a key is valid.

       */

      function keybEditGetValid() {

             return this.valid.toString();

      }

      /**

       * Return an error message associated with a key stroke.

       * @method getMessage

       * @return string Error message.

       */

      function keybEditGetMessage() {

             return this.message;

      }

}

/**

 * The purpose of this function is to edit edit keyboard input to determine if

 * the keystrokes are valid.

 * @requires keybEdit

 * @param {Object} evt

 * @param {Object} objKeyb

 */

function editKeyBoard(evt, objKeyb) {

      var strWork = objKeyb.getValid();

      var strMsg = '';                                   // Error message

      var blnValidChar = false;                    // Valid character flag

      var intCode = evt.charCode == undefined ? evt.keyCode : evt.charCode;

      // Part 1: Validate input

      if(!blnValidChar)

             switch(true) {

                   case(intCode == 8):

                   case(intCode == 9):

                   case(intCode == 10):

                   case(intCode == 13):

                          blnValidChar = true;

                          break;

                   default:

                          for(i=0;i < strWork.length;i++)

                                if(intCode == strWork.charCodeAt(i)) {

                                      blnValidChar = true;

                                      break;

                                }

                          break;

             }

      // Part 2: Build error message

      if(!blnValidChar) {

             if(objKeyb.getMessage().toString().length != 0)

                   alert('Error: ' + objKeyb.getMessage());

             evt.stopPropagation = true;

             try {

                   evt.preventDefault();

             }

             catch(e) {

                   window.event.returnValue = false;            // Clear invalid character

             }

      }

}

// ]]> -->

使用上述JavaScript代码作为输入需要再一次进入DOS命令提示符，如图E所示。该图还显示了生成文档所需的命令。图F显示的是文档的部分内容。

图E

生成文档过程

图F

生成的文档

选项和提示
从我所举的不完善的例子中你可能会发现，这个例子仅仅触及JSDoc的一些基本功能。为全面了解JSDoc的所有功能，你需要查看表A，其中列出了一些你可以在JavaScript文档中使用的标签。

表A

除上面提供的信息外，在JSDoc.pl命令后增加-h或-help选项，就会显示在生成文档时可以使用的选项列表。图G显示的是使用帮助选项的结果。

图G

-help选项

没有太多借口
虽然由JSDoc生成的文档可能与你的本地标准不一致，但它确实提供了一个起点。假如说，例如本地标准是UML，那么你可能想要使用-format选项试图生成XMI。有了JSDoc，似乎不创建文档的借口也在变少。

查看本文国际来源