Как описать аргументы "объекта" в jsdoc?

Я вижу, что уже есть ответ о теге @return, но я хочу дать более подробную информацию об этом.

во-первых, официальная документация JSDoc 3 не дает нам никаких примеров о @return для пользовательского объекта. Пожалуйста, смотрите http://usejsdoc.org/tags-returns.html теперь давайте посмотрим, что мы можем сделать, пока не появится какой-то стандарт.

• функция возвращает объект, в котором ключи генерируются динамически. Пример: {1: 'Pete', 2: 'Mary', 3: 'John'}. Обычно мы перебираем этот объект с помощью for(var key in obj){...}.

  возможный JSDoc согласно 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
  }
  

• функция возвращает объект, где ключи являются известными константами. Пример: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Мы можем легко получить доступ к свойствам этого объекта: object.id.

  возможный JSDoc согласно https://groups.google.com/forum/#! topic/jsdoc-users/TMvUedK9tC4

  • Фейк Это.

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

  • Все Сполна.

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

  • определить тип.

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

  согласно https://google.github.io/styleguide/javascriptguide.xml#JsTypes

  • запись тип.

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

в настоящее время существует 4 различных способа документирования объектов в качестве параметров/типов. Каждый из них имеет свое собственное применение. Однако только 3 из них можно использовать для документирования возвращаемых значений.

для объектов с известным набором свойств (вариант а)

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

этот синтаксис идеально подходит для объектов, которые используются только в качестве параметров для этой функции и не требуют дальнейшего описания каждого свойства. Это можно использовать для @returns как ну.

для объектов с известным набором свойств (вариант B)

очень полезно параметры со свойствами синтаксис:

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

этот синтаксис идеально подходит для объектов, которые используются только в качестве параметров для этой функции и, которые требуют дальнейшего описания каждого свойства. Это не может быть использовано для @returns.

для объектов, которые будут использоваться более чем в одной точке источник

в данном случае a @typedef поставляется в очень удобно. Вы можете определить тип в одной точке вашего источника и использовать его в качестве типа для @param или @returns или другие теги JSDoc, которые могут использовать тип.

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

затем вы можете использовать это в @param теги:

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

для объектов, значения которых имеют одинаковый тип

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

первый тип (строка) документирует тип ключей, которые в JavaScript всегда есть строка или, по крайней мере, всегда будет принуждаться к строке. Второй тип (число) - это тип значения; это может быть любой тип. Этот синтаксис можно использовать для @returns как хорошо.

ресурсы

полезную информацию о типах документирования можно найти здесь:

http://usejsdoc.org/tags-type.html

PS:

для документирования необязательного значения можно используйте []:

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

или:

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

на @return использовать тег {{field1: Number, field2: String}}, см.:http://wiki.servoy.com/display/public/DOCS/Annotating + JavaScript + использование+JSDoc

есть новый @config тег для таких случаев. Они ссылаются на предыдущий @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
 */