Javascript文档
JsDoc是一个针对javascript语言的文档生成器。这个工具是用来生成HTML格式的javascript源代码文档的，它类似于java语言中的Javadoc。强大的文档是成功的软件应用的因素之一。JSDoc解析带有内容的javascript源，并输出HTML文档。
这篇博文涵盖了JSDoc的教程和实例
安装和设置JSDoc
要玩这个，首先，你需要安装它。安装时提供了命令行工具 -jsdoc。这个库可作为npm包管理器。首先要确保Nodejs已经安装，npm和node命令通过以下命令成功运行。
B:\blogger>npm --version
5.6.0
B:\blogger>node --version
v8.10.0
一旦安装了nodejs，下一步就是安装jsDoc npm包。
npm install -g jsdoc
这将把jsdoc包安装在一个全局位置。我是在windows上进行安装的。请看windows上的全局npm安装位置，这是一个npm位置的文件夹，在窗口上是%APPDATA%/npm/node_modules/jsdoc。这是node_modules模块文件夹的全局位置。要找到jsdoc的版本，请发出以下命令
B:\blogger>jsdoc --version
JSDoc 3.5.5 (Thu, 14 Sep 2017 02:51:54 GMT)
JSDoc基本例子
用两个参数声明的简单函数，其返回类型是helloworld.js中的示例代码。
/**
* Adding two numbers.
* @param {value1} firstParameter First parameter to add.
* @param {value2} secondParameter Second Parameter to add.
* @returns {string}
*/
function add(value1, value2) {
return value1+value2;
}
然后运行下面的命令来生成HTML文档。
jsdoc helloworld.js
生成的HTML文件如下面的截图所示
语法
/**
* Adding two numbers.
* @param {string} firstParameter First parameter to add.
* @param {string} secondParameter Second Parameter to add.
* @returns {string}
*/
解释
- Jsdoc包含多行注释，除了第一个字符是星号外，每个注释都包括符号@和标签名称。@param是这里的一个标签 注释类型，它包括大括号中的类型名称 @param {string} name
注释与多行注释相似，不同的是多了一个星号 符号 注释也包含HTML标签
// Single line comment
/*
* multi-line comment
*/
/**
* Jsdoc comments
*/
JSDoc函数示例
在函数中添加了几个元标记 @fileOverview,@Author,@Version
/**
* This is a hello world function.
* @fileOverview Employee functions.
* @author [Kiran Babu](mailto:support@cloudhadoop.com)
* @version 1.0.0
* @param {string} value - A string param
* @return {string} Return a string
*
* @example
*
- displayEmp('Welcome')
*/
function displayEmp(msg) { return msg }
如何将方法返回为空？
你必须使用 @return标签 来记录方法函数的类型。类型可以在大括号中使用 在javascript中，void作为类型存在，你也可以使用undefined。
@returns {void} returns nothing
@returns {undefined} returns undefiend
jsdoc中有效的param标签类型是什么？@param标签是用来给函数或方法标记参数类型的。你也可以用*@arg或@argument来代替@param @tag*包含了一个函数的参数的名称、类型和描述。
/**
* @param {string} argument name of the employee.
*/
这里，名称是参数，类型是用大括号括起来的字符串，描述是雇员的名字。你可以使用javascript内置的数据类型作为参数类型的值，布尔，空，数字，字符串，未定义，符号，对象，可选和默认的参数声明 使用@param标签声明的参数，要使它成为这个param选项。让我们声明可选的参数，比如说字符串类型的信息。
@param {string} [message] // or
@param {string=} message
@param {string} [message='hello'] // defualt value initlization
如何声明混合类型的参数？
在方法或函数声明中，使用|符号分隔符为单个参数添加多种类型。
/**
* Utility method
* @param {(string|number)} argument The input parameter to function
* @returns {(string|number)} The modified return value from a function.
*/
function doSomething(argument) {
return argument;};
如何表示一个多维数组的对象参数类型？多维是一个对象的数组。在jsdoc的注释中可以用类型--对象来表示。
Jsdoc提供了一个 @callback标签 。它有关于回调函数的参数和返回值等信息。
/**
* Callback for multiplying two numbers.
*
* @callback multiCallback
* @param {int} multiply - An integer.
*/
/**
* Multiply two numbers, output the results to a callback function.
*
* @param {int} x - An integer.
* @param {int} y - An integer.
* @param {multiCallback} callback - A callback to execute.
*/
function Multiply(a, b, multiCallback) {
multiCallback(a*b);
}
如何记录javascript类？
@class或@constrcutor用来标记它是一个类或结构，可以用new操作符创建。
/**
* Creates a new Employee.
* @class Employee class
*/
function Employee() {
/** @lends Employee */
{
/**
* Create a `Employee` instance.
* @param {string} name - The Employee's name.
*/
initialize: function(name) {
this.name = name;
},
}
var e = new Employee();
@lend标签用于记录一个类的所有成员。
JSDoc经常使用的注释
Jsdoc支持以下标签，并提到了语法。所有这些语法都应该在jsdoc语法中使用（在多行注释中添加星号）
标签:
说明
用途/语法
@Author:
添加代码的作者，支持添加电子邮件
@author Kiran
@class:
标记功能，作为一个类实例可以使用新的关键字创建
@class 雇员类
@构造器:
将函数作为一个构造函数，与@class相同。
@构造函数 雇员类
@删除的:
指定一个注释，告诉大家这个方法将被废弃。
@从2.5版本开始被弃用
@throws：
表示一个方法可能抛出的异常或错误。
@throws {Exception} 异常@throws 如果参数为空，会抛出一个错误
@param:
为方法或函数的参数添加文档
@param {Number} numericValue 对参数的数值。
@private:
将此标记为私有
@private
@return 或 @returns:
方法或函数的返回值文件。
@returns {string}
@版本：
一个代码的版本号。
@version 1.0
@interface：
这使得作为接口
@interface 动物
@静态：
静态变量的标记，可以不通过实例访问。
@静态
@typedef：
自定义数据类型的标记。这些可以在其他标记中使用，就像普通的类型参数一样
@typedef {(number|string)} customType
@todo：
记录未来需要完成的事情
@todo 为这个方法写边缘案例和文档。
@借贷：
记录一个类或对象的所有成员
@借贷 雇佣
