Como descrever argumentos de "objeto" no jsdoc?

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

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 ).

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

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 || {}
        }
    }
    

Para @returnuso de tags {{field1: Number, field2: String}}, consulte: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

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

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