Cómo documentar las propiedades del objeto en la etiqueta JSDoc 3: @this

Question

La etiqueta @param permite la documentación de las propiedades, p.

/** 
    * @param {Object} userInfo Information about the user. 
    * @param {String} userInfo.name The name of the user. 
    * @param {String} userInfo.email The email of the user. 
    */ 

¿Cómo documentaré las propiedades de la etiqueta @this?

/** 
    * @this {Object} 
    * @param {String} this.name The name of the user. 
    * @param {String} this.email The email of the user. 
    */ 

Me pregunto si alguien que trabaja en el proyecto sabe. (Los documentos aún se están creando ...)

Answer 1

Para documentar los miembros de instancia, utilizar @name Class#member:

/** 
    Construct a new component 

    @class Component 
    @classdesc A generic component 

    @param {Object} options - Options to initialize the component with 
    @param {String} options.name - This component's name, sets {@link Component#name} 
    @param {Boolean} options.visible - Whether this component is vislble, sets {@link Component#visible} 
*/ 
function Component(options) { 
    /** 
    Whether this component is visible or not 

    @name Component#visible 
    @type Boolean 
    @default false 
    */ 
    this.visible = options.visible; 

    /** 
    This component's name 

    @name Component#name 
    @type String 
    @default "Component" 
    @readonly 
    */ 
    Object.defineProperty(this, 'name', { 
    value: options.name || 'Component', 
    writable: false 
    }); 
} 

Esto da como resultado una sección Miembros en la documentación que enumera cada miembro, su tipo, valor predeterminado y si es de solo lectura.

La salida generada por jsdoc@3.3.0-alpha3 como se ve así:

Ver también:

• JSDoc namepaths
• @instance tag
• @readonly tag
• @type tag

Answer 2

Utilice la etiqueta @property para describir el atributo de un objeto.

@param se utiliza para definir los parámetros de un método o constructor.

@this se usa para definir qué objeto this se refiere a. Así que aquí es un ejemplo usando jsdoc 3.

/** 
* @class Person 
* @classdesc A person object that only takes in names. 
* @property {String} this.name - The name of the Person. 
* @param {String} name - The name that will be supplied to this.name. 
* @this Person 
*/ 
var Person = function(name){ 
    this.name = name; 
}; 

jsdoc 3: https://github.com/jsdoc3/jsdoc

Más información: http://usejsdoc.org/index.html

Más información: http://code.google.com/p/jsdoc-toolkit/wiki/TagParam

Answer 3

Dentro del constructor de una clase, jsdoc se dará cuenta por sí mismo de que las propiedades documentadas pertenecen a las clases de intances. Por lo que este debe ser lo suficientemente:

/** 
* @classdesc My little class. 
* 
* @class 
* @memberof module:MyModule 
* @param {*} myParam Constructor parameter. 
*/ 
function MyLittleClass(myParam) { 
    /** 
    * Instance property. 
    * @type {string} 
    */ 
    this.myProp = 'foo'; 
} 

Si no está claro para jsdoc que la función es el constructor de la clase, se puede utilizar @this definir lo this se refiere a:

/** 
* @classdesc My little class. 
* 
* @class 
* @memberof module:MyModule 
* @name MyLittleClass 
* @param {*} myParam Constructor parameter. 
*/ 

// Somewhere else, the constructor is defined: 
/** 
* @this module:MyModule.MyLittleClass 
*/ 
function(myParam) { 
    /** 
    * Instance property. 
    * @type {string} 
    */ 
    this.myProp = 'foo'; 
}