前端架构之路(4) - 前端开发文档

前端开发文档

1. 为什么需要 “前端开发文档”

上一节讲到开发规范,不以规矩,不成方圆,团队开发离不开规范,这一节讲的开发文档是对开发规范的一个补充。

从目的上讲,规范与文档都是为了降低团队的协作成本和维护成本,提高开发效率和质量,保证不会因为开发人员的变动而产生较大的影响。

2. 哪些需要形成文档

2.1 注释(只讨论 js

随着前端的发展,文档已经慢慢的变得不可或缺了,并由社区的努力而形成了 JSDoc,类似 JavaDoc 和 PHPDoc。

2.1.1 什么是 JSDoc

JSDoc 是一个根据 javascript 文件中注释信息,生成 JavaScript 应用程序或库、模块的 API 文档 的工具。你可以使用他记录如:命名空间,类,方法,方法参数等,并且很多编辑器和 IDE 都是直接支持智能提示的。

2.1.2 JSDoc 注释示例

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;
    }
};

2.1.3 JSDoc 标签一览

  • {@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: 版本

2.1.4 把注释生成文档的工具

  • jsdoc: 官方提供的工具
  • documentation.js: 另外一个可供选择的工具,支持生成 htmlmarkdownjson
  • dox: tj 大神的作品

2.2 业务逻辑、更新日志与备注

另外一个需要记录的信息就是业务逻辑、更新日志与备注。

2.2.1 业务逻辑

有些比较复杂的业务逻辑不太适合放在注释里面,需要单独写逻辑文档,以备后面查看。

有时候,有些逻辑并不是简单的用文字描述就能说的清楚的,还需要图表或者思维导图的辅助。

2.2.2 更新日志

更新日志也是一个比较重要文档,能够方便查找更新状态、时间、开发人员等。

2.2.3 备注

如果有额外的一些信息,需要用文档备注一下。

3. 后续

上一篇:前端开发规范

下一篇:构建工具 for teamwork

参考文章:

  1. JSDoc 中文文档

更多博客,查看 https://github.com/senntyou/blogs

作者:深予之 (@senntyou)

版权声明:自由转载-非商用-非衍生-保持署名(创意共享3.0许可证

相关推荐