La mejor manera de documentar objetos anónimos y funciones con jsdoc

Question

Editar: Esto es técnicamente una pregunta de 2 partes. Elegí la mejor respuesta que cubre la pregunta en general y está vinculada a la respuesta que maneja la pregunta específica.

¿Cuál es la mejor manera de documentar objetos y funciones anónimas con jsdoc?

/** 
* @class {Page} Page Class specification 
*/ 
var Page = function() { 

    /** 
    * Get a page from the server 
    * @param {PageRequest} pageRequest Info on the page you want to request 
    * @param {function} callback Function executed when page is retrieved 
    */ 
    this.getPage = function(pageRequest, callback) { 
    }; 
}; 

Ni el objeto PageRequest o la callback existen en código. Se proporcionarán a getPage() en tiempo de ejecución. Pero me gustaría poder definir qué objeto y función son.

puedo salirse con la creación del objeto PageRequest para documentar que:

/** 
* @namespace {PageRequest} Object specification 
* @property {String} pageId ID of the page you want. 
* @property {String} pageName Name of the page you want. 
*/ 
var PageRequest = { 
    pageId : null, 
    pageName : null 
}; 

Y eso está bien (aunque estoy abierto a mejores maneras de hacer esto).

¿Cuál es la mejor manera de documentar la función callback? Quiero que sea conocido en el documento que, por ejemplo, la función de devolución de llamada está en la forma de:

callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus) 

¿Alguna idea de cómo hacer esto?

Answer 1

puede documentar cosas que no lo existe en el código mediante el uso de la etiqueta @ name:

 /** Description of the function 
      @name IDontReallyExist 
      @function 
      @param {String} someParameter Description 
     */ 


     /** The CallAgain method calls the provided function twice 
      @param {IDontReallyExist} func The function to call twice 
     */ 
     exports.CallAgain = function(func) { func(); func(); } 

Aquí es el @name tag documentation. Usted podría encontrar name paths útil también.

Answer 2

Puede usar @see para vincular a otro método dentro de la misma clase. El método nunca se usaría, simplemente estaría allí para fines de documentación.

/** 
* @class {Page} Page Class specification 
*/ 
var Page = function() { 

    /** 
    * Get a page from the server 
    * @param {PageRequest} pageRequest Info on the page you want to request 
    * @param {function} callback Function executed when page is retrieved 
    * @see #getPageCallback 
    */ 
    this.getPage = function (pageRequest, callback) { 
    }; 

    /** 
    * Called when page request completes 
    * @param {PageResponse} pageResponse The requested page 
    * @param {PageRequestStatus} pageRequestStatus Status of the page 
    */ 
    //#ifdef 0 
    this.getPageCallback = function (pageResponse, pageRequestStatus) { }; 
    //#endif 
}; 

Si está utilizando algún tipo de sistema de compilación, el método ficticio podría omitirse fácilmente de la compilación.

Answer 3

@link pueden agregar enlaces en línea a métodos y clases.

/** 
* Get a page from the server 
* @param {PageRequest} pageRequest Info on the page you want to request 
* @param {function} callback Function executed when page is retrieved<br /> 
* function({@link PageResponse} pageResponse,{@link PageRequestStatus} pageRequestStatus) 
*/ 
this.getPage = function (pageRequest, callback) { 
}; 

No es ideal, pero hace su trabajo.

Answer 4

Las anotaciones del compilador de cierres de Google tienen Type Expressions para esto, que incluye la capacidad de indicar el tipo para argumentos específicos, tipo de retorno e incluso esto. Muchas bibliotecas están siguiendo las Anotaciones del Compilador de Cierre de Google, porque quieren usarlo para reducir su código. Entonces tiene algo de impulso. El inconveniente es que no veo una forma de dar la descripción.

Para proporcionar la descripción, quizás el enfoque de JSDoc Toolkit Parameters With Properties funcionaría (consulte la parte inferior de la página). Es lo que estoy haciendo en este momento. JSDoc Toolkit está preparándose para comenzar a trabajar en V3, por lo que los comentarios podrían ser buenos.

Answer 5

Para complementar la respuesta de studgeek, he proporcionado un ejemplo que muestra lo que JsDoc with Google Closure Compiler le permite hacer.

Tenga en cuenta que los tipos anónimos documentados se eliminan del archivo minificado generado y el compilador asegura que se pasen los objetos válidos (cuando sea posible).Sin embargo, incluso si no usa el compilador, puede ayudar al próximo desarrollador y herramientas como WebStorm (IntelliJ) a entenderlo y darle la finalización del código.

// This defines an named type that you don't need much besides its name in the code 
// Look at the definition of Page#getPage which illustrates defining a type inline 
/** @typedef { pageId : string, pageName : string, contents: string} */ 
var PageResponse; 

/** 
* @class {Page} Page Class specification 
*/ 
var Page = function() {  
    /** 
    * Get a page from the server 
    * @param {PageRequest} pageRequest Info on the page you want to request 
    * 
    * The type for the second parameter for the function below is defined inline 
    * 
    * @param {function(PageResponse, {statusCode: number, statusMsg: string})} callback 
    *  Function executed when page is retrieved 
    */ 
    this.getPage = function(pageRequest, callback) { 
    }; 
}; 

Answer 6

Puede utilizar @callback o @typedef.

/** 
* @callback arrayCallback 
* @param {object} element - Value of array element 
* @param {number} index - Index of array element 
* @param {Array} array - Array itself 
*/ 

/** 
* @param {arrayCallback} callback - function applied against elements 
* @return {Array} with elements transformed by callback 
*/ 
Array.prototype.map = function(callback) { ... }