Come documentare le proprietà dell'oggetto nel tag JSDoc 3: @questo

Question

Il tag @param consente la documentazione delle proprietà, ad es.

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

Come posso documentare le proprietà del tag @questo?

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

mi chiedo se tutti coloro che lavorano al progetto lo sa. (I documenti sono ancora in fase di creazione ...)

Answer 1

per documentare i membri di istanza, utilizzare @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 
    }); 
} 

Ciò comporta una sezione Membri nella documentazione che elenca ciascun membro, il suo tipo, il valore predefinito e se è di sola lettura.

L'output come generato da jsdoc@3.3.0-alpha3 assomiglia a questo:

Vedi anche:

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

Answer 2

Utilizzare il tag @property per descrivere l'attributo di un oggetto.

@param viene utilizzato per definire i parametri di un metodo o costruttore.

@this viene utilizzato per definire a quale oggetto si riferisce this. Quindi, ecco un esempio con 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

Maggiori informazioni: http://usejsdoc.org/index.html

Maggiori informazioni: http://code.google.com/p/jsdoc-toolkit/wiki/TagParam

Answer 3

All'interno del costruttore di una classe, jsdoc si renderà conto da solo che le proprietà documentate appartengono a intances classe. Quindi questo dovrebbe essere sufficiente:

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

Se non è chiaro per jsdoc che la funzione è il costruttore della classe, è possibile utilizzare @this per definire ciò che this si riferisce 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'; 
}