К настоящему времени существует 4 различных способа документировать объекты как параметры / типы. У каждого свое использование. Только 3 из них могут быть использованы для документирования возвращаемых значений.
Для объектов с известным набором свойств (вариант А)
/**
* @param {{a: number, b: string, c}} myObj description
*/
Этот синтаксис идеально подходит для объектов, которые используются только в качестве параметров для этой функции и не требуют дальнейшего описания каждого свойства. Это может быть использовано @returns
также .
Для объектов с известным набором свойств (вариант Б)
Очень полезны параметры с синтаксисом свойств :
/**
* @param {Object} myObj description
* @param {number} myObj.a description
* @param {string} myObj.b description
* @param {} myObj.c description
*/
Этот синтаксис идеален для объектов, которые используются только в качестве параметров для этой функции и требуют дальнейшего описания каждого свойства. Это не может быть использовано для @returns
.
Для объектов, которые будут использоваться более чем в одной точке источника
В этом случае @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
*/
Или в @returns
:
/**
* @returns {Person} Description
*/
Для объектов, значения которых имеют одинаковый тип
/**
* @param {Object.<string, number>} dict
*/
Первый тип (строка) документирует тип ключей, который в JavaScript всегда является строкой или, по крайней мере, всегда будет приведен к строке. Второй тип (число) - это тип значения; это может быть любой тип. Этот синтаксис также может быть использован для @returns
.
Ресурсы
Полезную информацию о типах документирования можно найти здесь:
https://jsdoc.app/tags-type.html
PS:
для документирования необязательного значения вы можете использовать []
:
/**
* @param {number} [opt_number] this number is optional
*/
или:
/**
* @param {number|undefined} opt_number this number is optional
*/