Javascript代码注释及文档生成

3,042 views

Published on

Published in: Self Improvement
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
3,042
On SlideShare
0
From Embeds
0
Number of Embeds
86
Actions
Shares
0
Downloads
28
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

Javascript代码注释及文档生成

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

×