guides.json格式说明:
[ { "title": "Ext JS 4 Guides", "items": [ { "name": "getting_started", "url": "guides/getting_started", "title": "Getting Started with Ext JS 4", "description": "This introduction to Ext JS 4 explains how you can get started." }, { "name": "class_system", "url": "guides/class_system", "title": "The Class System", "description": "Creating classes with the new class system in Ext JS 4.x." }, { "name": "custom_url", "url": "guides/custom_file.md", "title": "The Class System", "description": "Creating classes with the new class system in Ext JS 4.x." }, { "title": "Subgroup of guides", "items": [ ... ] } ... ] }, ... ]guids.json内的文档对应目录结构:必须有README.md,README.md放内容,图片引用本地图片
具体参考:https://github.com/senchalabs/jsduck/wiki/Guides
somedir/
guides.json
guides/
getting_started/
README.md
icon.png
some-image.png
class_system/
README.md
icon.png
example.zip
custom_file.md
Detailed docs for using all the builtin tags:
示例:
/** * 抽象方法,一般为继承机制中公共的方法提到上一层时使用 * @abstract */ show: function() { alert("not implemented"); }
示例
/** * @cfg {Ext.data.Store} store (required) * 自动生成setter与getter方法,不建议使用 * @accessor */ store: undefined
- @alias 不建议使用,会在顶部生成一个
PeopleView source...xtype: grid
示例:
/** * @class Ext.grid.Panel * 别名的应用 * @alias widget.grid * @alias widget.gridpanel */
- @alternateClassName 不建议使用
/** * @class Ext.panel.Panel * 等同的名称,不建议使用 * @alternateClassName Ext.Panel * @alternateClassName XPanel */
ALTERNATE NAMES
Test2
生成向导,需要指定guides.json的路径,如:
jsduck-5.3.2.exe ./js -o ./docs --guides=guides.json
[
{
"title": "test",
"items": [
{
"name": "getting_started",
"url": "guides/getting_started",
"title": "Getting Started with Ext JS 4",
"description": "This introduction to Ext JS 4 explains how you can get started."
}
]
}
]
{
"title": "test",
"items": [
{
"name": "getting_started",
"url": "guides/getting_started",
"title": "Getting Started with Ext JS 4",
"description": "This introduction to Ext JS 4 explains how you can get started."
}
]
}
]
注意目录结构要符合上面的内容,会生成向导快捷链接
作者:
@author zx
示例:
/**
* 配置项目描述
* @cfg {Object} size 大小
* @cfg {Number} size.height 初始化配置高度
* @cfg {Number} size.width 初始化配置宽度
*/
* 配置项目描述
* @cfg {Object} size 大小
* @cfg {Number} size.height 初始化配置高度
* @cfg {Number} size.width 初始化配置宽度
*/
@cfg {Type} name (required)
Documentation for the config option.
@cfg {Type} [name="default value"] Documentation for the config option.
当函数返回this对象,加上此标识,表示可以继续.函数执行
- @class 两种格式
@class
Documentation for the class.
@class ClassName
Documentation for the class.
一个类只能有一个构造函数
/** * @class Ext.Panel * The one-and-only panel class. * * @constructor * Creates a new Panel instance. * @param {Object} [config] Configuration. */
不建议使用的内容
文档的作考,与author类似
/**
* @enum {Object} People.sex 性别
*/
sex:{
/**
* @property {String} [man] 男
*/
man:'男',
/**
* @property {String} [female] 女
*/
female:'女'
}
* @enum {Object} People.sex 性别
*/
sex:{
/**
* @property {String} [man] 男
*/
man:'男',
/**
* @property {String} [female] 女
*/
female:'女'
}
/**
* @event addPeople 人员增加
* @param {People} people 人员
*/
* @event addPeople 人员增加
* @param {People} people 人员
*/
暂时忽略,没什么用,事件参数调整标签
Generates documentation for
"<cfg-name>change"
event of evented config option. Only has an effect when used together with @accessor tag
示例:注意,@example与*之间必须保持四个空格以上
* See the example:
*
* @example
* new People("abc","efg")
*/
*
* @example
* new People("abc","efg")
*/
方法或类将会被移除的表示,后面可以跟版本号
@experimental
Some description...
@experimental 2.0 Some description...
继承
会把父类的公有方法都继续过去
- @fires (in 5.x beta)
事件触发说明
/** * Shows the component * @fires show */ show: function() { this.setVisible(true); this.fireEvent("show", this); },
可以忽略,与alias相同
Writing
@ftype foo
is shorthand for @alias feature.foo
隐藏,子类继承父类时,希望一些内容可以隐藏
如果有些方法子类不需要,则@hide即可,文档中不会显示出来
整个类不在用的时候,直接在前面增加标识
与static配合使用,加上该注释,子类也会存在该静态内容
如果与类注解一样的情况下,可以使用此方式,
@inheritdoc
@inheritdoc ClassName
@inheritdoc #memberName
@inheritdoc ClassName#memberName
@inheritdoc ClassName#static-type-memberName
- @localdoc (in 5.x beta)
当使用inheritdoc引用其他注释时,localdoc的注释内容,可以用本地的代替,如:
/** * Adds a listener for an event. * @localdoc See also the {@link #on} shorthand. 这部分不会被引用 * @param {String} event Name of the event to listen. * @param {Function} callback A function to execute. * @param {Object} scope A this value. */ addListener: function(event, callback, scope) { }, /** * @inheritdoc #addListener * @localdoc Shorthand alias for {@link #addListener} 这部分会替代引用中被标识的部分 */ on: function() { this.addListener.apply(this, arguments); }
标识说明向后兼容,可以忽略,因为默认就是向后兼容的
- @link
- 形成一个快捷的链接
Listen to the {@link Ext.data.Store#event-load load event}
指定归属,后面跟类名 @member People
- @method
-
/** 指定为方法 * @method area * Returns area of a circle * @param {Number} r Radius of the circle. * @return {Number} The area */
- @mixins
@mixins ClassName
在头部中会出现该类,方便快速链接
表示最近新增的方式,与@since成对比,@since表示从哪个版本开始支持的
@param name
Some description...
@param {Type} name
Some description...
@param {Type} [name]
Some description...
@param {Type} [name="default-value"]
Some description...
@param {Type} name.subproperty
Some description...
/** * @param {Array} args (optional) Arguments for the function. */
与@event配合使用,当有该标记时,表示如果事件return false后,该事件会中止
私有方法标识
属性标识
@property
Documentation for the property.
@property name
Documentation for the property.
@property {Type} name
Documentation for the property.
@property {Type} [name="default value"]
Documentation for the property.
@property {Type} name.subproperty
Documentation for the subproperty.
受保护的方式
设置属性为只读
移除,后面可以跟版本号与描述信息
组合模式下,说明依赖关系
/** * @class Ext.panel.Table * Basis of both TreePanel and GridPanel. * @requires Ext.selection.RowModel * @requires Ext.grid.header.Container */
- @return
-
/**与param差不多的应用方式 * @return {Object} A user record * @return {String} return.name The name of the user. * @return {String} return.email The email of the user. */
- @scss mixin
-
/**可忽略 * Creates an awesome button. * * @param {string} $ui-label The name of the UI being created. * @param {color} [$color=red] Base color for the UI. */ @mixin my-button($ui-label, $color: red) { }
- @since
@since Ext JS 4.0 beta 说明从哪个版本开始提供的
表示单例,单例不能有静态方式或属性
可以不太关注,一般与protected标识的方式同用
Documents a method which is provided as a hook for extending the functionality of the class. This tag usually goes along with @protected
@throws
Some description...
@throws {Type}
Some description...
可以忽略,与property相同的功能,该标识可以不用
标识该类需要使用的类,与requires差不多
Documents the SCSS variable: its name, type and default value.
可忽略
可忽略
Also for the inline tags:
- {@link} 建议快捷链接点
{@link Class#member link text}
{@img path/to/image.png alt text}
图片显示
Various tags use {TypeDefinitions}
, the syntax for these is described here:
参考资料:https://github.com/senchalabs/jsduck/wiki/Inline-examples