Más contenido relacionado
Similar a Javascript代码注释及文档生成
Similar a Javascript代码注释及文档生成 (20)
Javascript代码注释及文档生成
- 2. 代码注释及文档的必要性
一个优秀的js框架包括：
1.健壮可扩展的架
构
4.完善的 2.良好的
Debug机
文档系统
制
3. 多样的Unit Test
模块
- 3. 代码注释及文档的必要性
完善的文档有利于别人快速了解你的代
码结构和使用方法，提高团队的开发效
率。
文档的自动化必不可少
但是JS作为一门松散型解释语言，多变
的代码结构给文档自动化带来一定难
度， What’s
the
有什么解决方案么？ solution???
- 4. 自动文档系统的解决方案
使用开源项目jsdoc-toolkit
优点：
jsdoc-toolkit是基于java的文档生成系
统，基于mogzilla的rhino项目
（JDK1.6的ScriptEngine中已加入这
feature）,全部代码为js实现，懂得
javascript的程序员就可以进行2次开
发
- 5. 自动文档系统的解决方案
2jsdoc有良好的plugin机制和模板系
统，
便于生成使用与特定项目的文档,支持
多语言。
基于java可以快速集成到j2ee build环
境中
- 6. JS注释规范
基本注释：
@author 作者
@version 版本信息 {@link 连接目标}
@param {变量类型} 变量名 注释描述
@returns {返变量类型} 注释描述
@type 变量类型 @throws {错误类
型}
@private @public
@constructor @constant
@class 类名 注释描述 @default
@namespace @ deprecated
- 7. JS注释规范
Jdsoc辅助注释：
@scope 类名 (闭包范围标记)
@name (标记名称)
@memberOf 类型名 （成员标
记）
@ignore （忽略标
记）
@static (标记为静态变量)
@event (标记为事件函数)
@extends 类名 (标明继承的父类)
@example (代码使用范例标
记)
……
- 8. JS注释规范
Meta Tags：
/**#nocode+*/ (忽略代码开始标
记）
/**#nocode-*/ （忽略代码结束标
记）
/**#@+*/ (共享注释开始标
记）
/**#@-*/ (共享注释开始标
记）
- 9. JS注释规范
注意事项及技巧：
/** */ 为jsdoc的注释上下文区域，如有
非需要注释的被容请使用/* */或//或者
使用nocode注释。
对与可选参数或变量可将变量或参数名
加[]表示optional。如：
@{String} [pval]
- 10. JS注释规范
注意事项及技巧：
对于函数参数变量可使用行注释
如：
function foo(/**String*/arg0,/**Number*/arg1){}
等价于:
/**
*@param {String} arg0
*@param {Number} arg1
*/
function foo(/**String*/arg0,/**Number*/arg1){}
- 11. JS注释规范
注意事项及技巧：
Foo# 等价于 Foo.prototype
对不能识别的闭包使用@scope声明作
用域
- 12. JS注释规范
注意事项及技巧：
要充分利用jsdoc的代码伪注释机制，
可以让jsdoc对不能识别的闭包区间或
方法进行解析。（此为常用技巧，必须
掌握）
- 16. 项目实际使用设想
1. 对jsdoc进行改造，增加对现在FDEV
的框架的适用性
2. 修改模板生成js的lib代码，辅助jsdt的
lib import机制（类似java），方便于
开发人员
3. 对FDEV类的framework采用整体build
机制，对其它些common的widget类js
文件采用在线文档生成和索引机制，
方便分享
