jsDuck的注释说明

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

示例：

/**
 * 抽象方法，一般为继承机制中公共的方法提到上一层时使用
 * @abstract  
 */
show: function() {
    alert("not implemented");
}

• @accessor

示例

/**
 * @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
   
   

• @aside

生成向导,需要指定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."
                }
            ]
        }
    ]

注意目录结构要符合上面的内容,会生成向导快捷链接

• @author

作者：

@author zx

• @cfg

 示例：    

       /**
* 配置项目描述
* @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.

• @chainable

当函数返回this对象,加上此标识,表示可以继续.函数执行

• @class 两种格式

@class
Documentation for the class.

@class ClassName
Documentation for the class.

• @constructor

一个类只能有一个构造函数

/**
 * @class Ext.Panel
 * The one-and-only panel class.
 *
 * @constructor
 * Creates a new Panel instance.
 * @param {Object} [config] Configuration.
 */

• @deprecated

不建议使用的内容

• @docauthor

文档的作考,与author类似

• @enum

     /**
     * @enum {Object} People.sex 性别
     */
    sex:{
        /**
         * @property {String} [man] 男
         */
        man:'男',
        /**
         * @property {String} [female] 女
         */
        female:'女'
    }

• @event

/**
     * @event addPeople 人员增加
     * @param {People} people 人员
     */

• @evented 

暂时忽略,没什么用,事件参数调整标签

Generates documentation for "<cfg-name>change" event of evented config option. Only has an effect when used together with @accessor tag

• @example

示例:注意,@example与*之间必须保持四个空格以上

 * See the example:
 *
 *     @example
 *       new People("abc","efg")
 */

• @experimental

方法或类将会被移除的表示,后面可以跟版本号

@experimental
Some description...

@experimental 2.0 Some description...

• @extends

继承

会把父类的公有方法都继续过去

• @fires (in 5.x beta)

事件触发说明

/**
 * Shows the component
 * @fires show
 */
show: function() {
    this.setVisible(true);
    this.fireEvent("show", this);
},

• @ftype

可以忽略,与alias相同

Writing @ftype foo is shorthand for @alias feature.foo




• @hide

隐藏,子类继承父类时,希望一些内容可以隐藏

如果有些方法子类不需要,则@hide即可,文档中不会显示出来

• @ignore

整个类不在用的时候,直接在前面增加标识

• @inheritable

与static配合使用,加上该注释,子类也会存在该静态内容

• @inheritdoc

如果与类注解一样的情况下,可以使用此方式,

@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);
}

• @markdown

标识说明向后兼容,可以忽略,因为默认就是向后兼容的

• @link
• 形成一个快捷的链接

Listen to the {@link Ext.data.Store#event-load load event}

• @member

指定归属,后面跟类名 @member People

• @method

• /** 指定为方法
   * @method area
   * Returns area of a circle
   * @param {Number} r Radius of the circle.
   * @return {Number} The area
   */

  
  
• @mixins

@mixins ClassName

在头部中会出现该类,方便快速链接

• @new

表示最近新增的方式,与@since成对比,@since表示从哪个版本开始支持的

• @override

• 重现哪个类的方法

• @override OverriddenClassName

  
  
• @param 注意:变量名如果用方括号,表示可选参数

@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.
 */

• @preventable

与@event配合使用,当有该标记时,表示如果事件return false后,该事件会中止

• @private

私有方法标识

• @property

属性标识

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

• @protected

受保护的方式

• @ptype
• 可忽略
• Writing @ptype foo is shorthand for @alias plugin.foo
• 
  
• @readonly

设置属性为只读

• @removed

移除,后面可以跟版本号与描述信息

• @requires

组合模式下,说明依赖关系

/**
 * @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 说明从哪个版本开始提供的

• @singleton

表示单例,单例不能有静态方式或属性

• @static
• @template

可以不太关注,一般与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

@throws
Some description...

@throws {Type}
Some description...

• @type

可以忽略,与property相同的功能,该标识可以不用

• @uses

标识该类需要使用的类,与requires差不多

• @var

Documents the SCSS variable: its name, type and default value.

可忽略

• @xtype

可忽略

Also for the inline tags:

• {@link} 建议快捷链接点

{@link Class#member link text}

• {@img}

{@img path/to/image.png alt text}

图片显示

• {@video}

Various tags use {TypeDefinitions}, the syntax for these is described here:

• Type Definitions

参考资料:https://github.com/senchalabs/jsduck/wiki/Inline-examples