Upgrade to Pro — share decks privately, control downloads, hide ads and more …

JSDoc 的使用

Sponsored · Your Podcast. Everywhere. Effortlessly. Share. Educate. Inspire. Entertain. You do you. We'll handle the rest. →
Avatar for Frank Xu Frank Xu
July 08, 2011
Programming
170
0

JSDoc 的使用

深入探索 JsDoc 的使用细节

Avatar for Frank Xu

Frank Xu

July 08, 2011

More Decks by Frank Xu

See All by Frank Xu
Proxy Pattern
Avatar for Frank Xu yyfrankyy
0
110
微信读书阅读器架构
Avatar for Frank Xu yyfrankyy
2
2.3k
Watcher - EventBus Reinvented
Avatar for Frank Xu yyfrankyy
0
170
SQLite 调优实践
Avatar for Frank Xu yyfrankyy
0
160
FtnApp 的缩略图实践
Avatar for Frank Xu yyfrankyy
0
77
交易平台化（前端）
Avatar for Frank Xu yyfrankyy
0
200
淘宝搜索前端优化
Avatar for Frank Xu yyfrankyy
0
220
淘宝排行榜 V3 项目总结
Avatar for Frank Xu yyfrankyy
0
150

Other Decks in Programming

See All in Programming
メソッドのジェネリクスでGoの夢は広がるか？ / Kyoto.go #65
Avatar for utagawa kiki utgwkk
3
920
エンジニア向け会社紹介/Findy Company Profile
Avatar for Findy findyinc
6
350k
生成AI時代にこそ効くGo | Why Go Works in the Age of Generative AI
Avatar for mom0tomo mom0tomo
8
3.3k
そのテスト、説明できますか？~LWテスト戦略FW~のご紹介
Avatar for Kei Nakahara nakahara
0
160
AIだと陥りがちなJakarta EE最新技術への移行時の落とし穴と解決策
Avatar for tnagao7 tnagao7
0
120
Even G2とAWSで推しのエージェントを召喚しよう！
Avatar for Har1101 har1101
1
120
セキュリティの専門家じゃなくてもできる。「セキュリティ意識」をアップデートして サプライチェーン攻撃への耐性を高めよう。
Avatar for tk3fftk tk3fftk
5
920
肥大化するレガシーコードに立ち向かうためのインターフェース分離と依存の逆転 / JJUG CCC 2026 Spring
Avatar for hirokuni-maeta hirokunimaeta
0
610
代数的データ型って何が嬉しいの？ #frontend_phpcon_do
Avatar for Takuma Kajikawa kajitack
8
3.8k
気づいたらRubyで100作品 ー クリエイティブコーディングが生活の一部になるまで / 100 Ruby Sketches Later: How Creative Coding Became Part of My Life
Avatar for chobishiba chobishiba
3
610
Strategic Design in the Frontend: Moduliths & Micro Frontends @DDDEurope
Avatar for Manfred Steyer manfredsteyer
PRO
0
130
JavaDoc 再入門
Avatar for nagise nagise
1
410

Featured

See All Featured
Cheating the UX When There Is Nothing More to Optimize - PixelPioneers
Avatar for Stéphanie Walter stephaniewalter
287
14k
Designing Experiences People Love
Avatar for Jonathan Moore moore
143
24k
How People are Using Generative and Agentic AI to Supercharge Their Products, Projects, Services and Value Streams Today
Avatar for Helen Beal helenjbeal
1
220
[RailsConf 2023 Opening Keynote] The Magic of Rails
Avatar for Eileen M. Uchitelle eileencodes
31
10k
Breaking role norms: Why Content Design is so much more than writing copy - Taylor Woolridge
Avatar for UX Y'all uxyall
0
330
Building Better People: How to give real-time feedback that sticks.
Avatar for Will Jessup wjessup
370
20k
Introduction to Domain-Driven Design and Collaborative software design
Avatar for Kenny Baas-Schwegler baasie
1
860
Learning to Love Humans: Emotional Interface Design
Avatar for Aarron Walter aarron
275
41k
A Soul's Torment
Avatar for Nat Ma seathinner
6
3k
Neural Spatial Audio Processing for Sound Field Analysis and Control
Avatar for NII S. Koyama's Lab skoyamalab
0
340
Thoughts on Productivity
Avatar for Jon Yablonski jonyablonski
76
5.2k
Rails Girls Zürich Keynote
Avatar for Gregor Martynus gr2m
96
14k

Transcript

  1. JsDoc的使用 @yyfrankyy Yet Another JavaScript Programmer f2e.us July 8, 2011

    . . . . . .

  2. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Agenda 1 docco 2 JsDoc-Toolkit Introduction Annotations Tips @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  3. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit docco http://jashkenas.github.com/docco/ 小巧（100来行代码） 快速 易用（双斜杆注释+markdown语法） 各种语言都有自己的 docco @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  4. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit docco Docco is a quick-and-dirty, hundred-line-long, literate-programming-style documentation generator. It produces HTML that displays your comments alongside your code. Comments are passed through Markdown, and code is passed through Pygments syntax highlighting. This page is the result of running Docco against its own source file. @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  5. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit install & usage install $ sudo npm install docco -g $ docco sea.js @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  6. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit docco @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  7. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Introduction jsdoc-toolkit JsDoc Toolkit is an application, written in JavaScript, for automatically generating template-formatted, multi-page HTML (or XML, JSON, or any other text-based) documentation from commented JavaScript source code. @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  8. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Introduction 简介 http://code.google.com/p/jsdoc-toolkit/ 基于 @annotation 的API文档工具。 v2 不再继续开发新功能，v3 正在调研。 @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  9. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Introduction 简介 http://code.google.com/p/jsdoc-toolkit/ 基于 @annotation 的API文档工具。 v2 不再继续开发新功能，v3 正在调研。 基本用法 java -jar jsrun.jar app/run.js -r=4 tc/ -t=templates/jsdoc @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  10. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Introduction 基本特性 用js实现，运行在rhino上面。 支持模板。 文件内按注释块顺序解析。 @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  11. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations Annotations @fileoverview/@author/@license @param @name @description/@example @augments/@borrows/@lends @namespace/@class/@constructor @function/@field the others.. @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  12. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @fileoverview/@author/@license 文件模板 /** * @fileoverview 模块简介. * @author 文河<[email protected]> * * @license * Copyright (c) 2010 Taobao Inc. */ @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  13. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @param 基本用法 @param {类型} 变量名 描述. @param {类型[]} 变量名 描述. @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  14. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @param 基本用法 @param {类型} 变量名 描述. @param {类型[]} 变量名 描述. 可选参数和默认值 @param {类型} [变量名] 描述. @param {类型} [变量名="default"] 描述. @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  15. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @param 基本用法 @param {类型} 变量名 描述. @param {类型[]} 变量名 描述. 可选参数和默认值 @param {类型} [变量名] 描述. @param {类型} [变量名="default"] 描述. 配置参数，可选配置，默认值 @param {类型} config.params 描述. @param {类型} [config.params] 描述. @param {类型} [config.params="default"] 描述. @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  16. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @name 全文索引，默认为注释快后第一个token名。 全文共享，暴露局部变量可能引发局部变量的声明冲突。 设置@name，可改变当前变量的全文索引。 Example /** * name of this account. * */ var name = "frank"; @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  17. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @name 全文索引，默认为注释快后第一个token名。 全文共享，暴露局部变量可能引发局部变量的声明冲突。 设置@name，可改变当前变量的全文索引。 Example /** * name of this account. * @name wenhe */ var name = "frank"; @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  18. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @description/@example 无tag的信息并入@description。 可通过@link/@see进行相互链接。 @example输出<pre/>标签。 顺序解析，直接转为html（无换行），有markdown插件。 @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  19. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @description/@example 无tag的信息并入@description。 可通过@link/@see进行相互链接。 @example输出<pre/>标签。 顺序解析，直接转为html（无换行），有markdown插件。 Example /** * name of this account. * @description * other desc. * @example * Form.add("hello"); */ @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  20. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @description/@example 无tag的信息并入@description。 可通过@link/@see进行相互链接。 @example输出<pre/>标签。 顺序解析，直接转为html（无换行），有markdown插件。 Example /** * name of this account. * @description * other desc. * @example * Form.add("hello"); */ @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  21. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @description/@example 无tag的信息并入@description。 可通过@link/@see进行相互链接。 @example输出<pre/>标签。 顺序解析，直接转为html（无换行），有markdown插件。 Example /** * name of this account. * @description * other desc. * @example * Form.add("hello"); */ Example name of this account. other desc. Form.add("hello"); @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  22. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @augments/@lends/@borrows @augments 将目标对象的prototype并入当前的prototype。 @borrows 从目标对象借入单个方法/属性。 @lends 把整个对象借给其他对象。 @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  23. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations prototype/this JSDoc里描述prototype或者this，可用#代替 Example mobile.prototype === mobile# mobile.prototype.func === mobile#func this.func = #func @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  24. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @augments 描述基本的原型继承。 @augments /** @constructor */ function moduleBase() { }; @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  25. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @augments 描述基本的原型继承。 @augments /** @constructor */ function moduleBase() { }; /** @augments moduleBase */ function mobile() { }; @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  26. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @augments 描述基本的原型继承。 @augments /** @constructor */ function moduleBase() { }; /** @augments moduleBase */ function mobile() { }; @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  27. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @borrows/@lends @borrows 配合 @lends，描述Mixin机制。 @borrow /** @borrows EventTarget.fire as #fire */ var moduleBase = function() { }; @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  28. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @borrows/@lends @borrows 配合 @lends，描述Mixin机制。 @borrow /** @borrows EventTarget.fire as #fire */ var moduleBase = function() { }; @lends /** @constructor */ function mobile() { }; S.mix(mobile, /** @lends mobile */ { change: ; test: ; getMobile: ; .. }; @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  29. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @borrows/@lends @borrows 配合 @lends，描述Mixin机制。 @borrow /** @borrows EventTarget.fire as #fire */ var moduleBase = function() { }; @lends /** @constructor */ function mobile() { }; S.mix(mobile, /** @lends mobile */ { change: ; test: ; getMobile: ; .. }; @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  30. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @borrows/@lends @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  31. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @namespace/@class/@constructor @namespace 命名空间，输出一个没有参数，没有类型的节点。 @constructor 描述为一个构造器。 @class 描述为一个类。比constructor多了个多行描述。 @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  32. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @class/@constructor 任何在构造器上声明的参数均为初始化函数，new的时候传入。 @constructor /** * @name Mobile * @class 手机充值 * * @param {Object} config 初始配置. * @param {Object} [config.saveExtra] 额外保存信息. * ... * * @augments ModuleBase */ @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  33. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations @class/@constructor @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  34. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations the others.. @type 声明某个属性的类型，注意没有中括号。 @exports 用于模块重命名。会修改外部对某个变量的引用。 @memberof 自定义变量归属，自定义@name的时候使用。 @private 把一个公开方法标识为私有。 @public 把一个私有方法暴露出去。 @static 把一个方法标识为静态方法。 @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  35. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Annotations the others.. @returns 返回值，可以指定类型。有没有s都可以。 @ignore 忽略某些索引，对加了-p参数的时候有用。 @deprecated 标识这个方法不推荐继续使用。 @constant 标识为常量。 @event 事件，描述具有很多复杂事件的模块有用。 @field/@function 两者同一类型，指定某个变量为属性还是方法。 @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  36. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Tips last but not least 某种程度上，我们可以只写一些空的注释， 来完善整个JsDoc输出的索引列表。 @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  37. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Tips Example /** * @class 事件对象. * @name EventTarget */ /** * 监听事件 * @name on * @function * @memberof EventTarget * @param {String} event 事件名称. * @param {EventCallback} function 监听方法. */ @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  38. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Tips 描述回调函数的参数和返回值 空注释块，还能用来描述回调方法的类型，返回值等。 Example /** * @param {ajaxCallback} callback 回调方法. * @returns {Boolean} 回调处理是否成功. */ function(callback) { callback(data); } @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  39. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Tips 描述回调函数的参数和返回值 空注释块，还能用来描述回调方法的类型，返回值等。 Example /** * @name ajaxCallback * @param {Object} data 返回的数据. */ /** * @param {ajaxCallback} callback 回调方法. * @returns {Boolean} 回调处理是否成功. */ function(callback) { callback(data); } @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  40. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Tips 一些注意点 Windows下，注意仅大小写不同的模块， 输出的文件可能会覆盖。 @lends 不能写成 a.b.c 的形式。 仅能作为整体 {} 存在来写。 其他描述，对于局部变量 {} 大多无效。 改写成 a.b.c 的形式试试。 注意文件内是顺序解析的，注释也要顺序着写。 JsDoc还很不完美，但是需要的时候还是可以派上用场。 @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用

  41. . . . . . . Overview docco ... .............

    ..... JsDoc-Toolkit Tips 谢谢！ @yyfrankyy Yet Another JavaScript Programmer f2e.us JsDoc的使用