Download - Javascript代码注释及文档生成
![Page 1: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/1.jpg)
Javascript 代码注释及文档生成 jsdoc 等文档相关工具介绍 by Bruce.liz
![Page 2: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/2.jpg)
代码注释及文档的必要性一个优秀的 js 框架包括:
1. 健壮可扩展的架构
2. 良好的
Debug机制
3. 多样的 Unit Test 模块
4. 完善的文档
系统
![Page 3: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/3.jpg)
代码注释及文档的必要性完善的文档有利于别人快速了解你的
代码结构和使用方法,提高团队的开发效率。
文档的自动化必不可少
但是 JS 作为一门松散型解释语言,多变的代码结构给文档自动化带来一定难度,
有什么解决方案么? What’s the solution???
What’s the solution???
![Page 4: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/4.jpg)
自动文档系统的解决方案使用开源项目 jsdoc-toolkit
优点: jsdoc-toolkit 是基于 java 的文档生成
系统,基于 mogzilla 的 rhino 项目( JDK1.6 的 ScriptEngine 中已加入这feature ) , 全部代码为 js 实现,懂得javascript 的程序员就可以进行 2 次开发
![Page 5: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/5.jpg)
自动文档系统的解决方案 2jsdoc 有良好的 plugin 机制和模板
系统, 便于生成使用与特定项目的文档 , 支持
多语言。
基于 java 可以快速集成到 j2ee build 环境中
![Page 6: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/6.jpg)
JS 注释规范基本注释: @author 作者 @version 版本信息 {@link 连接目标 } @param { 变量类型 } 变量名 注释描述 @returns { 返变量类型 } 注释描述 @type 变量类型 @throws { 错误类型 } @private @public @constructor @constant @class 类名 注释描述 @default @namespace @ deprecated
![Page 7: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/7.jpg)
JS 注释规范Jdsoc 辅助注释: @scope 类名 ( 闭包范围标记 ) @name ( 标记名称 ) @memberOf 类型名 (成员标记) @ignore (忽略标记) @static ( 标记为静态变量 ) @event ( 标记为事件函数 ) @extends 类名 ( 标明继承的父类 ) @example ( 代码使用范例标记 ) ……
![Page 8: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/8.jpg)
JS 注释规范Meta Tags : /**#nocode+*/ ( 忽略代码开始
标记) /**#nocode-*/ (忽略代码结束
标记) /**#@+*/ ( 共享注释开始
标记) /**#@-*/ ( 共享注释开始
标记)
![Page 9: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/9.jpg)
JS 注释规范注意事项及技巧: /** */ 为 jsdoc 的注释上下文区域,
如有非需要注释的被容请使用 /* */ 或 // 或者使用 nocode 注释。
对与可选参数或变量可将变量或参数名加 [] 表示 optional 。如:
@{String} [pval]
![Page 10: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/10.jpg)
JS 注释规范注意事项及技巧: 对于函数参数变量可使用行注释如: function foo(/**String*/arg0,/**Number*/arg1){}
等价于 :/** *@param {String} arg0 *@param {Number} arg1 */function foo(/**String*/arg0,/**Number*/arg1)
{}
![Page 11: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/11.jpg)
JS 注释规范注意事项及技巧: Foo# 等价于 Foo.prototype
对不能识别的闭包使用 @scope 声明作用域
![Page 12: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/12.jpg)
JS 注释规范注意事项及技巧: 要充分利用 jsdoc 的代码伪注释机制,
可以让 jsdoc 对不能识别的闭包区间或方法进行解析。(此为常用技巧,必须掌握)
![Page 13: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/13.jpg)
jsdoc 实战演示环节Let’s go!
![Page 14: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/14.jpg)
关于 jsdoc 的二次开发改造Jsdoc 主要逻辑为 js 代码因此前端程
序员能很好的进行二次开发。本身 jsdoc 提供了 plugin 的机制,可
以以插件形式在解析注释的时候加入自己的逻辑。
Jsdoc 的文档输出是基于 JsPlate 模板系统,
可以方便的定制 html 文档的输出格式。……
![Page 15: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/15.jpg)
Jsdoc 实际使用时辅助工具Jsdoc 可配合 eclipse 的插件方便的使
用注释。如 myeclipse8+ 或 eclipse WTP ( 两者都使用的是 JSDT 的 plugin, 此
插件也可单独安装,需要 eclipse 3.6+)
![Page 16: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/16.jpg)
项目实际使用设想1. 对 jsdoc 进行改造,增加对现在
FDEV 的框架的适用性2. 修改模板生成 js 的 lib 代码,辅助
jsdt 的 lib import 机制(类似java ),方便于开发人员
3. 对 FDEV 类的 framework采用整体build 机制,对其它些 common 的widget 类 js 文件采用在线文档生成和索引机制,方便分享
![Page 17: Javascript代码注释及文档生成](https://reader031.vdocuments.mx/reader031/viewer/2022013108/55892e1ad8b42a27388b4686/html5/thumbnails/17.jpg)
最后引言要实现文档自动化离不开每个人的配合,希望大家能从繁琐的手写文档中解放出来,提高代码质量,更好的与别人分享代码
Enjoy it! Thanks