上一节讲到开发规范，不以规矩，不成方圆，团队开发离不开规范，这一节讲的开发文档是对开发规范的一个补充。
从目的上讲，规范与文档都是为了降低团队的协作成本和维护成本，提高开发效率和质量，保证不会因为开发人员的变动而产生较大的影响。
随着前端的发展，文档已经慢慢的变得不可或缺了，并由社区的努力而形成了 JSDoc，类似 JavaDoc 和 PHPDoc。
2.1.1 什么是 JSDoc
JSDoc 是一个根据 javascript 文件中注释信息，生成 JavaScript 应用程序或库、模块的 API 文档 的工具。你可以使用他记录如：命名空间，类，方法，方法参数等，并且很多编辑器和 IDE 都是直接支持智能提示的。
JSDoc 注释一般应该放置在方法或函数声明之前，它必须以 /** 开始，其他任何以 /*，/*** 或者超过 3 个星号的注释，都将被 JSDoc 解析器忽略。例如：
/**
* Book类，代表一个书本.
* @constructor
* @param {string} title - 书本的标题.
* @param {string} author - 书本的作者.
*/
function Book(title, author) {
this.title=title;
this.author=author;
}
Book.prototype={
/**
* 获取书本的标题
* @returns {string|*}
*/
getTitle:function(){
return this.title;
},
/**
* 设置书本的页数
* @param pageNum {number} 页数
*/
setPageNum:function(pageNum){
this.pageNum=pageNum;
}
};
{@link: ...}, {@linkplain: ...}, {@linkcode: ...}, {@tutorial: ...}: 内联标签@abstract: 抽象，必须由继承者实现（或者覆盖）@access: 访问级别（private、public 或者 protected）@alias: 别名@augments: 参数@author: 作者@borrows: 借用@callback: 回调函数@classdesc: 类描述@constant: 常量@constructor: 构造函数，可以使用 new 创建一个实例@constructs: 构造@copyright: 版权@default: 默认值@deprecated: 弃用的@desc: 描述@enum: 枚举值@event: 事件@example: 范例@exports: 模块导出（模块化）@external: 外部模块（模块化）@file: 文件@fires: 可触发的事件@global: 全局对象@ignore: 忽略@inner: 内联对象@instance: 实例@kind: 标识类型@lends: 遍历属于同一个标识的所有属性@license: 软件授权@link: 内联@member: 成员@memberof: 属于某成员@method: 方法@mixes: 合并@mixin: 最小化@module: 模块（模块化）@name: 名称@namespace: 命名空间@param: 参数@private: 私有的（访问控制）@property: 属性@protected: 受保护的（访问控制）@public: 公开的（访问控制）@readonly: 只读的@requires: 依赖（模块化）@return: 返回值@see: 引用@since: 开始于@static: 静态的@summary: 概述@this: 解释 this 关键字@throws: 可能抛出的异常@todo: 待办事项@tutorial: 引用指导手册@type: 类型@typedef: 自定义类型@variation: 区分不同的对象具有相同名称的@version: 版本
- jsdoc: 官方提供的工具
- documentation.js: 另外一个可供选择的工具，支持生成
html，markdown，json - dox: tj 大神的作品
另外一个需要记录的信息就是业务逻辑、更新日志与备注。
有些比较复杂的业务逻辑不太适合放在注释里面，需要单独写逻辑文档，以备后面查看。
有时候，有些逻辑并不是简单的用文字描述就能说的清楚的，还需要图表或者思维导图的辅助。
更新日志也是一个比较重要文档，能够方便查找更新状态、时间、开发人员等。
如果有额外的一些信息，需要用文档备注一下。
参考文章：
更多博客，查看 https://github.com/deepraining/blogs
版权声明：自由转载-非商用-非衍生-保持署名（创意共享 3.0 许可证）