web-dev-qa-db-fra.com

Meilleure façon de documenter des objets et des fonctions anonymes avec jsdoc

Edit: C'est techniquement une question en 2 parties. J'ai choisi la meilleure réponse qui couvre la question en général et liée à la réponse qui traite la question spécifique.

Quelle est la meilleure façon de documenter des objets et des fonctions anonymes avec 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 l'objet PageRequest ni callback n'existent dans le code. Ils seront fournis à getPage() lors de l'exécution. Mais j'aimerais pouvoir définir l'objet et la fonction.

Je peux m'en tirer en créant l'objet PageRequest pour documenter 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
};

Et c'est très bien (même si je suis ouvert à de meilleures façons de le faire).

Quelle est la meilleure façon de documenter la fonction callback? Je veux faire savoir dans le document que, par exemple, la fonction de rappel se présente sous la forme de:

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

Des idees pour faire cela?

javascriptdocumentationtagsjsdoc
58
Josh Johnson

Vous pouvez documenter des éléments qui n'existent pas dans le code en utilisant la balise @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(); }

Voici la documentation @ nom tag . Vous pourriez également trouver chemins de noms utiles.

44
Eric

Vous pouvez utiliser @callback ou @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) { ... }
36
kzh

Pour complimenter la réponse de studgeek, j'ai fourni un exemple qui montre ce que JsDoc avec Google Closure Compiler vous permet de faire.

Notez que les types anonymes documentés sont supprimés du fichier minifié généré et le compilateur garantit que les objets valides sont transmis (lorsque cela est possible). Cependant, même si vous n'utilisez pas le compilateur, il peut aider le prochain développeur et des outils comme WebStorm (IntelliJ) à le comprendre et à vous donner du code.

// 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) {
    }; 
};
8
Juan Mendes

Les annotations du compilateur de fermeture Google ont Expressions de type pour cela, ce qui inclut la possibilité d'indiquer le type pour des arguments spécifiques, le type de retour, et même cela. De nombreuses bibliothèques envisagent de suivre les annotations du compilateur de fermeture Google, car elles souhaitent l'utiliser pour réduire leur code. Il y a donc un élan. L'inconvénient est que je ne vois pas de moyen de donner la description.

Pour fournir la description, peut-être l'approche JSDoc Toolkit Paramètres avec propriétés fonctionnerait (regardez au bas de la page). C'est ce que je fais en ce moment. Le JSDoc Toolkit se prépare à commencer à travailler sur la V3, donc les retours peuvent être bons.

1
studgeek

@link peut ajouter des liens en ligne vers des méthodes et des classes.

/**
 * 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) {
};

Pas idéal, mais ça fait le travail.

1
Josh Johnson

Vous pouvez utiliser @see pour créer un lien vers une autre méthode de la même classe. La méthode ne serait jamais utilisée, elle serait juste là à des fins de documentation.

/**
 * @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 vous utilisez une sorte de système de build, la méthode factice pourrait facilement être omise de la build.

0
Dagg Nabbit