javascript - documentar - jsdoc example

La mejor forma 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 ni la callback existen en el código. Se proporcionarán para getPage() en tiempo de ejecución. Pero me gustaría poder definir qué objeto y función son.

Puedo salir con la creación del objeto PageRequest para documentar eso:

/**
 * @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 formas de hacerlo).

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

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

¿Alguna idea de como hacer esto?

Answer 1

Las anotaciones del compilador de cierre de Google tienen expresiones de tipo 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 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 2

Para complementar la respuesta de Studgeek, he proporcionado un ejemplo que muestra lo que JsDoc con Google Closure Compiler te permite hacer.

Tenga en cuenta que los tipos anónimos documentados se eliminan del archivo minificado generado y el compilador asegura que los objetos válidos se transfieren (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 3

Puede documentar cosas que no existen en el código utilizando 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í está la documentación de la etiqueta @name . Puede encontrar rutas de nombre útiles también.

Answer 4

Puede usar @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) { ... }

Answer 5

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 6

@link puede 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 el trabajo bien.