Como descrever argumentos de "objeto" no 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) {
}

Mas como descrevo como o objeto de parâmetros deve ser estruturado? Por exemplo, deve ser algo como:

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

Respostas:

428

Na página wiki do @param :


Parâmetros com propriedades

Se se espera que um parâmetro tenha uma propriedade específica, você pode documentá-lo imediatamente após a tag @param desse parâmetro, da seguinte forma:

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

Costumava haver uma tag @config que seguia imediatamente o @param correspondente, mas parece ter sido preterido ( exemplo aqui ).

Jonny Buchanan
fonte
17
infelizmente a tag retornos não parecem ter um equivalente code.google.com/p/jsdoc-toolkit/wiki/TagReturns
Michael Bylstra
1
Nesta resposta semelhante, stackoverflow.com/a/14820610/3094399, eles também adicionaram as opções @param {Object} no início. Acho que pode ser redundante.
pcatre 23/01
Você tem algum exemplo com os parâmetros de desestruturação do ES6? No meu caso, não tenho o actionnome, escrevo `foo = ({arg1, arg2, arg2}) => {...}`. Edit: question here stackoverflow.com/questions/36916790/…
Eric Burel 13/03
alguma idéia de como documentar um membro do objeto que é opção? Quero dizer, meu objeto de usuário deve ter nome de usuário e pode ter nome completo. Então, como faço para especificar que o nome completo é opcional?
Yash Kumar Verma
167

Até agora, existem 4 maneiras diferentes de documentar objetos como parâmetros / tipos. Cada um tem seus próprios usos. Apenas 3 deles podem ser usados ​​para documentar valores retornados.

Para objetos com um conjunto conhecido de propriedades (Variante A)

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

Essa sintaxe é ideal para objetos que são usados ​​apenas como parâmetros para esta função e não exigem descrição adicional de cada propriedade. Ele pode ser usado para @returnsbem .

Para objetos com um conjunto conhecido de propriedades (Variante B)

Muito úteis são os parâmetros com sintaxe de propriedades :

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

Essa sintaxe é ideal para objetos que são usados ​​apenas como parâmetros para esta função e que exigem descrição adicional de cada propriedade. Isso não pode ser usado para @returns.

Para objetos que serão usados ​​em mais de um ponto na origem

Nesse caso, um @typedef é muito útil. Você pode definir o tipo em um ponto da sua origem e usá-lo como um tipo para @paramou @returnsou outras tags JSDoc que podem fazer uso de um tipo.

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

Você pode usar isso em uma @paramtag:

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

Ou em um @returns:

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

Para objetos cujos valores são todos do mesmo tipo

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

O primeiro tipo (string) documenta o tipo de chave que no JavaScript sempre é uma string ou, pelo menos, sempre será coagida a uma string. O segundo tipo (número) é o tipo do valor; isso pode ser de qualquer tipo. Essa sintaxe também pode ser usada @returns.

Recursos

Informações úteis sobre os tipos de documentação podem ser encontradas aqui:

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

PS:

para documentar um valor opcional, você pode usar []:

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

ou:

/**
 * @param {number|undefined} opt_number this number is optional
 */
Simon Zyx
fonte
A variante 1 funciona com vários tipos de uma propriedade? Gosta {{dir: A|B|C }}?
CMCDragonkai
Qualquer anotação de tipo deve ser possível aqui, então sim
Simon Zyx
E para objetos cujas chaves são geradas dinamicamente? Como{[myVariable]: string}
Frondor 10/01/19
135

Vejo que já existe uma resposta sobre a tag @return, mas quero fornecer mais detalhes sobre ela.

Primeiro, a documentação oficial do JSDoc 3 não fornece exemplos sobre o @return para um objeto personalizado. Consulte https://jsdoc.app/tags-returns.html . Agora, vamos ver o que podemos fazer até que algum padrão apareça.

  • A função retorna o objeto em que as chaves são geradas dinamicamente. Exemplo: {1: 'Pete', 2: 'Mary', 3: 'John'}. Geralmente, iteramos sobre esse objeto com a ajuda de for(var key in obj){...}.

    Possível JSDoc de acordo com 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
    }
    
  • A função retorna o objeto em que as chaves são constantes conhecidas. Exemplo: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Podemos facilmente acessar propriedades desse objeto: object.id.

    Possível JSDoc de acordo com https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

    • Falsificá-lo.

      /**
       * 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
          }
      }
      
    • O montante todo.

      /**
       @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);
      }
      
    • Defina um 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
          }
      }
      

    De acordo com https://google.github.io/styleguide/javascriptguide.xml#JsTypes

    • O tipo de registro.

      /**
       * @return {{myNum: number, myObject}}
       * An anonymous type with the given type members.
       */
      function getTmpObject() {
          return {
              myNum: 2,
              myObject: 0 || undefined || {}
          }
      }
      
vogdb
fonte
Alguém está ciente de uma maneira de gerar isso no IntelliJ / Webstorm? Especificamente, estou falando da terceira opção - defina um tipo.
Erez Cohen
Por favor elabore. Deseja ter alguma tecla de atalho ou atalho no IDE para gerar esses documentos ou deseja que seu IDE os entenda? Talvez ambos?
vogdb
@vogdb, você poderia, por favor, dar uma olhada nessa questão? Acredito que este caso de uso não seja coberto com seus ótimos exemplos: stackoverflow.com/questions/53191739/…
Pavel Polyakov
@PavelPolyakov que eu olhei. Realmente não sei como responder sua pergunta. Estou sem JS por um tempo. Sinta-se livre para editar minha resposta, se você tiver alguma informação nova.
Vogdb 08/11/19
2

Se um parâmetro tiver uma propriedade específica, é possível documentar essa propriedade fornecendo uma tag @param adicional. Por exemplo, se um parâmetro de funcionário tiver propriedades de nome e departamento, você poderá documentá-lo da seguinte maneira:

/**
 * 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 um parâmetro for destruído sem um nome explícito, você poderá atribuir ao objeto um apropriado e documentar suas propriedades.

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

Karma Blackshaw
fonte
0

Há uma nova @configtag para esses casos. Eles apontam para o anterior @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
 */
Mike DeSimone
fonte
1
Você pode apontar para a documentação da @configtag? Não encontrei nada no usejsdoc.org , e esta página sugere @configque foi preterido.
Dan Dascalescu 30/07/2015
4
Eu acho que @configestá obsoleto neste momento. YUIDoc recomenda o uso @attribute.
Mike DeSimone