Il modo migliore per documentare oggetti anonimi e funzioni con jsdoc

Question

Modifica: Questa è tecnicamente una domanda in 2 parti. Ho scelto la risposta migliore che copre la domanda in generale e collegata alla risposta che gestisce la domanda specifica.

Qual è il modo migliore per documentare oggetti anonimi e funzioni 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) { 
    }; 
}; 

Né l'oggetto PageRequest o callback esistono nel codice. Saranno forniti a getPage() in fase di esecuzione. Ma mi piacerebbe essere in grado di definire cosa sono l'oggetto e la funzione.

posso ottenere via con la creazione dell'oggetto PageRequest per documentare che:

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

e va bene (anche se io sono aperto a modi migliori per farlo).

Qual è il modo migliore per documentare la funzione callback? Voglio farlo conoscere nel documento che, per esempio, la funzione di callback è sotto forma di:

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

Tutte le idee come fare questo?

Answer 1

è possibile documentare roba che pretende molto esiste nel codice utilizzando il tag @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(); } 

Ecco il @name tag documentation. Potresti trovare utile anche name paths.

Answer 2

È possibile utilizzare @see per collegarsi a un altro metodo all'interno della stessa classe. Il metodo non verrebbe mai utilizzato, sarebbe solo lì a scopo di documentazione.

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

Se si utilizza una sorta di sistema di generazione, il metodo fittizio potrebbe facilmente essere omesso dalla compilazione.

Answer 3

@link può aggiungere collegamenti in linea a metodi e classi.

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

Non ideale, ma ha il compito.

Answer 4

Le annotazioni del compilatore Google Closure hanno Type Expressions per questo che include la possibilità di indicare il tipo per argomenti specifici, tipo di reso e anche questo. Molte librerie stanno seguendo le Annotazioni del compilatore di Closure di Google, perché desiderano utilizzarle per ridurre il loro codice. Quindi ha un po 'di slancio. Lo svantaggio è che non vedo un modo per dare la descrizione.

Per fornire la descrizione, forse l'approccio JSDoc Toolkit Parameters With Properties funzionerebbe (guarda in fondo alla pagina). È quello che sto facendo adesso. Il toolkit JSDoc è pronto per iniziare a lavorare su V3, quindi il feedback potrebbe essere positivo.

Answer 5

Per complimentarmi con la risposta di studgeek, ho fornito un esempio che mostra cosa consente di fare JsDoc with Google Closure Compiler.

Si noti che i tipi anonimi documentati vengono rimossi dal file minificato generato e il compilatore assicura che gli oggetti validi siano passati (quando possibile).Tuttavia, anche se non si utilizza il compilatore, può aiutare il prossimo sviluppatore e strumenti come WebStorm (IntelliJ) a capirlo e a fornire il completamento del codice.

// 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

È possibile utilizzare @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) { ... }