Jak dokumentować właściwości obiektu w tagu JSDoc 3: @tis

Question

Znacznik @param umożliwia dokumentowanie właściwości, np.

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

Jak udokumentować właściwości tagu @this?

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

Zastanawiam się, czy ktoś, kto pracuje nad projektem, wie. (Dokumenty wciąż są tworzone ...)

Answer 1

celu udokumentowania członków przykład użyć @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 
    }); 
} 

Powoduje to, że sekcja Członkowie w sekcji w dokumentacji, która wymienia każdego członka, jego typ, wartość domyślną i czy jest tylko do odczytu.

Wyjście jak generowane przez jsdoc@3.3.0-alpha3 wygląda następująco:

Patrz także:

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

Answer 2

Użyj znacznika @property, aby opisać atrybut obiektu.

@param służy do definiowania parametrów metody lub konstruktora.

@this służy do określenia, którego obiektu dotyczy obiekt this. Tak oto przykład stosując 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

Więcej informacji: http://usejsdoc.org/index.html

Więcej informacji: http://code.google.com/p/jsdoc-toolkit/wiki/TagParam

Answer 3

W ramach konstruktora klasy jsdoc sam sobie sprawę, że udokumentowane właściwości należą do intencji klasowych. Tak to powinno wystarczyć:

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

Jeśli nie jest jasne dla JSDoc że funkcja jest konstruktor klasy, można użyć @this zdefiniować co this odnosi się do:

/** 
* @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'; 
}