JsDoc的使用

JsDoc的使用

@yyfrankyy

Yet Another JavaScript Programmer
f2e.us

July 8, 2011

. . . . . .

Overview docco JsDoc-Toolkit
...
.............
.....

Agenda

1 docco

2 JsDoc-Toolkit
Introduction
Annotations
Tips

. . . . . .

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

...
.............
.....

docco

http://jashkenas.github.com/docco/
小巧（100来行代码）
快速
易用（双斜杆注释+markdown语法）
各种语言都有自己的 docco

. . . . . .

JsDoc的使用

...
.............
.....

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.

. . . . . .

JsDoc的使用

...
.............
.....

install & usage

install
$ sudo npm install docco -g
$ docco sea.js

. . . . . .

JsDoc的使用

...
.............
.....

docco

. . . . . .

JsDoc的使用

...
.............
.....
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.

. . . . . .

JsDoc的使用

...
.............
.....
Introduction

简介

http://code.google.com/p/jsdoc-toolkit/
基于 @annotation 的API文档工具。
v2 不再继续开发新功能，v3 正在调研。

. . . . . .

JsDoc的使用

...
.............
.....
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

. . . . . .

JsDoc的使用

...
.............
.....
Introduction

基本特性

用js实现，运行在rhino上面。
支持模板。
文件内按注释块顺序解析。

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

Annotations

@fileoverview/@author/@license
@param
@name
@description/@example
@augments/@borrows/@lends
@namespace/@class/@constructor
@function/@field
the others..

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

@fileoverview/@author/@license

文件模板
/**
* @fileoverview 模块简介.
* @author 文河<wenhe@taobao.com>
*
* @license
* Copyright (c) 2010 Taobao Inc.
*/

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

@param
基本用法
@param {类型} 变量名描述.
@param {类型[]} 变量名描述.

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

@param
基本用法

可选参数和默认值
@param {类型} [变量名] 描述.
@param {类型} [变量名="default"] 描述.

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

@param
基本用法

可选参数和默认值
@param {类型} [变量名] 描述.
@param {类型} [变量名="default"] 描述.

配置参数，可选配置，默认值
@param {类型} config.params 描述.
@param {类型} [config.params] 描述.
@param {类型} [config.params="default"] 描述.
. . . . . .

JsDoc的使用

...
.............
.....
Annotations

@name

全文索引，默认为注释快后第一个token名。
全文共享，暴露局部变量可能引发局部变量的声明冲突。
设置@name，可改变当前变量的全文索引。

Example
/**
* name of this account.
*
*/
var name = "frank";
. . . . . .

JsDoc的使用

...
.............
.....
Annotations

@name

全文索引，默认为注释快后第一个token名。
全文共享，暴露局部变量可能引发局部变量的声明冲突。
设置@name，可改变当前变量的全文索引。

Example
/**
* @name wenhe
*/
var name = "frank";
. . . . . .

JsDoc的使用

...
.............
.....
Annotations

无tag的信息并入@description。
可通过@link/@see进行相互链接。
@example输出<pre/>标签。
顺序解析，直接转为html（无换行），有markdown插件。

. . . . . .

JsDoc的使用

...
.............
.....
Annotations


Example
/**
* @description
* other desc.
* @example
* Form.add("hello");
*/ . . . . . .

JsDoc的使用

...
.............
.....
Annotations


Example Example
/**
* name of this account. name of this account.
* @description other desc.
* other desc.
* @example Form.add("hello");
* Form.add("hello");
*/ . . . . . .

JsDoc的使用

...
.............
.....
Annotations

@augments/@lends/@borrows

@augments 将目标对象的prototype并入当前的prototype。
@borrows 从目标对象借入单个方法/属性。
@lends 把整个对象借给其他对象。

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

prototype/this

JSDoc里描述prototype或者this，可用#代替

Example
mobile.prototype === mobile#
mobile.prototype.func === mobile#func
this.func = #func

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

@augments

描述基本的原型继承。
@augments
/** @constructor */ function moduleBase() { };

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

@augments

描述基本的原型继承。
@augments
/** @constructor */ function moduleBase() { };
/** @augments moduleBase */ function mobile() { };

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

@borrows/@lends

@borrows 配合 @lends，描述Mixin机制。
@borrow
/** @borrows EventTarget.fire as #fire */
var moduleBase = function() { };

. . . . . .

JsDoc的使用

...
.............
.....
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: ; ..
};
. . . . . .

JsDoc的使用

...
.............
.....
Annotations

@borrows/@lends

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

@namespace/@class/@constructor

@namespace 命名空间，输出一个没有参数，没有类型的节点。
@constructor 描述为一个构造器。
@class 描述为一个类。比constructor多了个多行描述。

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

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

JsDoc的使用

...
.............
.....
Annotations

@class/@constructor

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

the others..

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

. . . . . .

JsDoc的使用

...
.............
.....
Annotations

the others..

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

. . . . . .

JsDoc的使用

...
.............
.....
Tips

last but not least

某种程度上，我们可以只写一些空的注释，
来完善整个JsDoc输出的索引列表。

. . . . . .

JsDoc的使用

...
.............
.....
Tips

Example
/**
* @class 事件对象.
* @name EventTarget
*/

/**
* 监听事件
* @name on
* @function
* @memberof EventTarget
* @param {String} event 事件名称.
* @param {EventCallback} function 监听方法.
*/
. . . . . .

JsDoc的使用

...
.............
.....
Tips

描述回调函数的参数和返回值
空注释块，还能用来描述回调方法的类型，返回值等。
Example

/**
* @param {ajaxCallback} callback 回调方法.
* @returns {Boolean} 回调处理是否成功.
*/
function(callback) { callback(data); }
. . . . . .

JsDoc的使用

...
.............
.....
Tips

描述回调函数的参数和返回值
空注释块，还能用来描述回调方法的类型，返回值等。
Example
/**
* @name ajaxCallback
* @param {Object} data 返回的数据.
*/

/**
* @param {ajaxCallback} callback 回调方法.
* @returns {Boolean} 回调处理是否成功.
*/
function(callback) { callback(data); }
. . . . . .

JsDoc的使用

...
.............
.....
Tips

一些注意点

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

. . . . . .

JsDoc的使用

...
.............
.....
Tips

谢谢！

. . . . . .

JsDoc的使用

JsDoc的使用

Recommandé

Recommandé

Contenu connexe

Similaire à JsDoc的使用

Similaire à JsDoc的使用 (20)

Plus de Frank Xu

Plus de Frank Xu (7)

JsDoc的使用