Come descrivere argomenti "oggetto" in jsdoc?


316
// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}

Ma come posso descrivere come strutturare l'oggetto parametri? Ad esempio dovrebbe essere qualcosa del tipo:

{
  setting1 : 123, // (required, integer)
  setting2 : 'asdf' // (optional, string)
}

Risposte:


428

Dalla pagina wiki di @param :


Parametri con proprietà

Se si prevede che un parametro abbia una proprietà particolare, è possibile documentarlo immediatamente dopo il tag @param per quel parametro, in questo modo:

 /**
  * @param userInfo Information about the user.
  * @param userInfo.name The name of the user.
  * @param userInfo.email The email of the user.
  */
 function logIn(userInfo) {
        doLogIn(userInfo.name, userInfo.email);
 }

C'era un tag @config che seguiva immediatamente il corrispondente @param, ma sembra essere stato deprecato ( esempio qui ).


17
purtroppo il tag rendimenti non sembra avere un equivalente code.google.com/p/jsdoc-toolkit/wiki/TagReturns
Michael Bylstra

1
In questa risposta simile stackoverflow.com/a/14820610/3094399 hanno anche aggiunto le opzioni @param {Object} all'inizio. Immagino che potrebbe essere ridondante però.
PCATRE

Hai qualche esempio con i parametri di destrutturazione ES6? Nel mio caso non ho il actionnome, scrivo `foo = ({arg1, arg2, arg2}) => {...}`. Modifica: domanda qui stackoverflow.com/questions/36916790/…
Eric Burel

qualche idea su come documentare un membro oggetto che è un'opzione? Voglio dire il mio oggetto utente dovrebbe avere un nome utente e può avere un nome completo. quindi come faccio a specificare che il nome completo è facoltativo
Yash Kumar Verma

167

Ormai ci sono 4 modi diversi per documentare gli oggetti come parametri / tipi. Ognuno ha i suoi usi. Tuttavia, solo 3 di questi possono essere utilizzati per documentare i valori restituiti.

Per oggetti con un set di proprietà noto (variante A)

/**
 * @param {{a: number, b: string, c}} myObj description
 */

Questa sintassi è ideale per gli oggetti che vengono utilizzati solo come parametri per questa funzione e non richiedono un'ulteriore descrizione di ciascuna proprietà. Esso può essere utilizzato per @returnspure .

Per oggetti con un set di proprietà noto (variante B)

Molto utili sono i parametri con sintassi delle proprietà :

/**
 * @param {Object} myObj description
 * @param {number} myObj.a description
 * @param {string} myObj.b description
 * @param {} myObj.c description
 */

Questa sintassi è ideale per gli oggetti che vengono utilizzati solo come parametri per questa funzione e che richiedono un'ulteriore descrizione di ciascuna proprietà. Questo non può essere usato per @returns.

Per oggetti che verranno utilizzati in più di un punto nell'origine

In questo caso un @typedef è molto utile. È possibile definire il tipo ad un certo punto nella vostra sorgente e utilizzarlo come un tipo per @paramo @returnso altri tag JSDoc che possono fare uso di un tipo.

/**
 * @typedef {Object} Person
 * @property {string} name how the person is called
 * @property {number} age how many years the person lived
 */

È quindi possibile utilizzare questo in un @paramtag:

/**
 * @param {Person} p - Description of p
 */

O in un @returns:

/**
 * @returns {Person} Description
 */

Per oggetti i cui valori sono tutti dello stesso tipo

/**
 * @param {Object.<string, number>} dict
 */

Il primo tipo (stringa) documenta il tipo di chiavi che in JavaScript è sempre una stringa o almeno sarà sempre costretta a una stringa. Il secondo tipo (numero) è il tipo del valore; questo può essere di qualsiasi tipo. Anche questa sintassi può essere utilizzata @returns.

risorse

Informazioni utili sui tipi di documentazione sono disponibili qui:

https://jsdoc.app/tags-type.html

PS:

per documentare un valore opzionale è possibile utilizzare []:

/**
 * @param {number} [opt_number] this number is optional
 */

o:

/**
 * @param {number|undefined} opt_number this number is optional
 */

La variante 1 funziona con più tipi di proprietà? Come {{dir: A|B|C }}?
CMCDragonkai,

Qualsiasi annotazione di tipo dovrebbe essere possibile qui, quindi sì
Simon Zyx,

E per gli oggetti le cui chiavi sono generate dinamicamente? Come{[myVariable]: string}
Frondor,

135

Vedo che esiste già una risposta sul tag @return, ma voglio fornire maggiori dettagli al riguardo.

Innanzitutto, la documentazione ufficiale di JSDoc 3 non ci fornisce alcun esempio di @return per un oggetto personalizzato. Si prega di consultare https://jsdoc.app/tags-returns.html . Ora vediamo cosa possiamo fare fino a quando appariranno alcuni standard.

  • La funzione restituisce l'oggetto in cui le chiavi vengono generate dinamicamente. Esempio: {1: 'Pete', 2: 'Mary', 3: 'John'}. Di solito, ripetiamo questo oggetto con l'aiuto di for(var key in obj){...}.

    Possibile JSDoc secondo https://google.github.io/styleguide/javascriptguide.xml#JsTypes

    /**
     * @return {Object.<number, string>}
     */
    function getTmpObject() {
        var result = {}
        for (var i = 10; i >= 0; i--) {
            result[i * 3] = 'someValue' + i;
        }
        return result
    }
  • La funzione restituisce un oggetto in cui le chiavi sono costanti note. Esempio: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Possiamo facilmente accedere alle proprietà di questo oggetto: object.id.

    Possibile JSDoc secondo https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

    • Fai finta.

      /**
       * Generate a point.
       *
       * @returns {Object} point - The point generated by the factory.
       * @returns {number} point.x - The x coordinate.
       * @returns {number} point.y - The y coordinate.
       */
      var pointFactory = function (x, y) {
          return {
              x:x,
              y:y
          }
      }
    • The Full Monty.

      /**
       @class generatedPoint
       @private
       @type {Object}
       @property {number} x The x coordinate.
       @property {number} y The y coordinate.
       */
      function generatedPoint(x, y) {
          return {
              x:x,
              y:y
          };
      }
      
      /**
       * Generate a point.
       *
       * @returns {generatedPoint} The point generated by the factory.
       */
      
      var pointFactory = function (x, y) {
          return new generatedPoint(x, y);
      }
    • Definisci un tipo.

      /**
       @typedef generatedPoint
       @type {Object}
       @property {number} x The x coordinate.
       @property {number} y The y coordinate.
       */
      
      
      /**
       * Generate a point.
       *
       * @returns {generatedPoint} The point generated by the factory.
       */
      
      var pointFactory = function (x, y) {
          return {
              x:x,
              y:y
          }
      }

    Secondo https://google.github.io/styleguide/javascriptguide.xml#JsTypes

    • Il tipo di record.

      /**
       * @return {{myNum: number, myObject}}
       * An anonymous type with the given type members.
       */
      function getTmpObject() {
          return {
              myNum: 2,
              myObject: 0 || undefined || {}
          }
      }

Qualcuno a conoscenza di un modo per generare questo in IntelliJ / Webstorm? In particolare, sto parlando della terza opzione: definire un tipo.
Erez Cohen,

Per favore, elabora. Vuoi avere qualche tasto di scelta rapida o scorciatoia in IDE per generare quel documento o vuoi che il tuo IDE comprenda quel documento? Forse entrambi?
Vogdb,

@vogdb potresti, per favore, dare un'occhiata a questo problema? Credo che questo caso d'uso non sia coperto dai tuoi grandi esempi: stackoverflow.com/questions/53191739/…
Pavel Polyakov

@PavelPolyakov che ho cercato. Non so davvero come rispondere alla tua domanda. Sono fuori di JS per un po '. Sentiti libero di modificare la mia risposta se hai nuove informazioni.
vogdb,


2

Se si prevede che un parametro abbia una proprietà specifica, è possibile documentare tale proprietà fornendo un tag @param aggiuntivo. Ad esempio, se si prevede che un parametro dipendente abbia proprietà nome e reparto, è possibile documentarlo come segue:

/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
function(employees) {
    // ...
}

Se un parametro viene destrutturato senza un nome esplicito, è possibile assegnare l'oggetto appropriato e documentarne le proprietà.

/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

Fonte: JSDoc


0

C'è un nuovo @configtag per questi casi. Si collegano al precedente @param.

/** My function does X and Y.
    @params {object} parameters An object containing the parameters
    @config {integer} setting1 A required setting.
    @config {string} [setting2] An optional setting.
    @params {MyClass~FuncCallback} callback The callback function
*/
function(parameters, callback) {
    // ...
};

/**
 * This callback is displayed as part of the MyClass class.
 * @callback MyClass~FuncCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */

1
Puoi indicare la documentazione per il @configtag? Non ho trovato nulla su usejsdoc.org e questa pagina suggerisce che @configè stato deprecato.
Dan Dascalescu il

4
Penso che @configsia deprecato a questo punto. Invece YUIDoc consiglia di utilizzare @attribute.
Mike DeSimone,
Utilizzando il nostro sito, riconosci di aver letto e compreso le nostre Informativa sui cookie e Informativa sulla privacy.
Licensed under cc by-sa 3.0 with attribution required.