Javascript 代码注释及文档生成 jsdoc 等文档相关工具介绍 by Bruce.liz

代码注释及文档的必要性一个优秀的 js 框架包括：

1. 健壮可扩展的架构

2. 良好的

Debug机制

3. 多样的 Unit Test 模块

4. 完善的文档

系统

代码注释及文档的必要性完善的文档有利于别人快速了解你的

代码结构和使用方法，提高团队的开发效率。

文档的自动化必不可少

但是 JS 作为一门松散型解释语言，多变的代码结构给文档自动化带来一定难度，

有什么解决方案么？ What’s the solution???

What’s the solution???

自动文档系统的解决方案使用开源项目 jsdoc-toolkit

优点： jsdoc-toolkit 是基于 java 的文档生成

系统，基于 mogzilla 的 rhino 项目（ JDK1.6 的 ScriptEngine 中已加入这feature ） , 全部代码为 js 实现，懂得javascript 的程序员就可以进行 2 次开发

自动文档系统的解决方案 2jsdoc 有良好的 plugin 机制和模板

系统， 便于生成使用与特定项目的文档 , 支持

多语言。

基于 java 可以快速集成到 j2ee build 环境中

JS 注释规范基本注释： @author 作者 @version 版本信息 {@link 连接目标 } @param { 变量类型 } 变量名 注释描述 @returns { 返变量类型 } 注释描述 @type 变量类型 @throws { 错误类型 } @private @public @constructor @constant @class 类名 注释描述 @default @namespace @ deprecated

JS 注释规范Jdsoc 辅助注释： @scope 类名 ( 闭包范围标记 ) @name ( 标记名称 ) @memberOf 类型名 （成员标记） @ignore （忽略标记） @static ( 标记为静态变量 ) @event ( 标记为事件函数 ) @extends 类名 ( 标明继承的父类 ) @example ( 代码使用范例标记 ) ……

JS 注释规范Meta Tags ： /**#nocode+*/ ( 忽略代码开始

标记） /**#nocode-*/ （忽略代码结束

标记） /**#@+*/ ( 共享注释开始

标记） /**#@-*/ ( 共享注释开始

标记）

JS 注释规范注意事项及技巧： /** */ 为 jsdoc 的注释上下文区域，

如有非需要注释的被容请使用 /* */ 或 // 或者使用 nocode 注释。

对与可选参数或变量可将变量或参数名加 [] 表示 optional 。如：

@{String} [pval]

JS 注释规范注意事项及技巧： 对于函数参数变量可使用行注释如： function foo(/**String*/arg0,/**Number*/arg1){}

等价于 :/** *@param {String} arg0 *@param {Number} arg1 */function foo(/**String*/arg0,/**Number*/arg1)

{}

JS 注释规范注意事项及技巧： Foo# 等价于 Foo.prototype

对不能识别的闭包使用 @scope 声明作用域

JS 注释规范注意事项及技巧： 要充分利用 jsdoc 的代码伪注释机制，

可以让 jsdoc 对不能识别的闭包区间或方法进行解析。（此为常用技巧，必须掌握）

jsdoc 实战演示环节Let’s go!

关于 jsdoc 的二次开发改造Jsdoc 主要逻辑为 js 代码因此前端程

序员能很好的进行二次开发。本身 jsdoc 提供了 plugin 的机制，可

以以插件形式在解析注释的时候加入自己的逻辑。

Jsdoc 的文档输出是基于 JsPlate 模板系统，

可以方便的定制 html 文档的输出格式。……

Jsdoc 实际使用时辅助工具Jsdoc 可配合 eclipse 的插件方便的使

用注释。如 myeclipse8+ 或 eclipse WTP ( 两者都使用的是 JSDT 的 plugin, 此

插件也可单独安装，需要 eclipse 3.6+)

项目实际使用设想1. 对 jsdoc 进行改造，增加对现在

FDEV 的框架的适用性2. 修改模板生成 js 的 lib 代码，辅助

jsdt 的 lib import 机制（类似java ），方便于开发人员

3. 对 FDEV 类的 framework采用整体build 机制，对其它些 common 的widget 类 js 文件采用在线文档生成和索引机制，方便分享

最后引言要实现文档自动化离不开每个人的配合，希望大家能从繁琐的手写文档中解放出来，提高代码质量，更好的与别人分享代码

Enjoy it! Thanks