// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}
Но как мне описать, как должен быть структурирован объект параметров? Например, это должно быть что-то вроде:
{
setting1 : 123, // (required, integer)
setting2 : 'asdf' // (optional, string)
}
javascript
jsdoc
Энди Хин
источник
источник
action
имени, я пишу `foo = ({arg1, arg2, arg2}) => {...}`. Изменить: здесь вопрос stackoverflow.com/questions/36916790/…К настоящему времени существует 4 различных способа документировать объекты как параметры / типы. У каждого свое использование. Только 3 из них могут быть использованы для документирования возвращаемых значений.
Для объектов с известным набором свойств (вариант А)
Этот синтаксис идеально подходит для объектов, которые используются только в качестве параметров для этой функции и не требуют дальнейшего описания каждого свойства. Это может быть использовано
@returns
также .Для объектов с известным набором свойств (вариант Б)
Очень полезны параметры с синтаксисом свойств :
Этот синтаксис идеален для объектов, которые используются только в качестве параметров для этой функции и требуют дальнейшего описания каждого свойства. Это не может быть использовано для
@returns
.Для объектов, которые будут использоваться более чем в одной точке источника
В этом случае @typedef очень удобен. Вы можете определить тип в одной точке источника и использовать его в качестве типа для
@param
или@returns
или других тегов JSDoc , которые могут сделать использование типа.Затем вы можете использовать это в
@param
теге:Или в
@returns
:Для объектов, значения которых имеют одинаковый тип
Первый тип (строка) документирует тип ключей, который в JavaScript всегда является строкой или, по крайней мере, всегда будет приведен к строке. Второй тип (число) - это тип значения; это может быть любой тип. Этот синтаксис также может быть использован для
@returns
.Ресурсы
Полезную информацию о типах документирования можно найти здесь:
https://jsdoc.app/tags-type.html
PS:
для документирования необязательного значения вы можете использовать
[]
:или:
источник
{{dir: A|B|C }}
?{[myVariable]: string}
Я вижу, что уже есть ответ о теге @return, но я хочу рассказать о нем подробнее.
Прежде всего, официальная документация по JSDoc 3 не дает нам примеров @return для пользовательского объекта. Пожалуйста, смотрите https://jsdoc.app/tags-returns.html . Теперь посмотрим, что мы можем сделать, пока не появится какой-то стандарт.
Функция возвращает объект, где ключи генерируются динамически. Пример:
{1: 'Pete', 2: 'Mary', 3: 'John'}
. Обычно мы перебираем этот объект с помощьюfor(var key in obj){...}
.Возможный JSDoc в соответствии с https://google.github.io/styleguide/javascriptguide.xml#JsTypes
Функция возвращает объект, ключи которого являются известными константами. Пример:
{id: 1, title: 'Hello world', type: 'LEARN', children: {...}}
. Мы можем легко получить доступ к свойствам этого объекта:object.id
.Возможный JSDoc в соответствии с https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4
Притворяться.
Полный Монти.
Определите тип.
Согласно https://google.github.io/styleguide/javascriptguide.xml#JsTypes
Тип записи.
источник
Для
@return
использования тегов{{field1: Number, field2: String}}
см .: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDocисточник
Источник: JSDoc
источник
Для
@config
этих случаев есть новый тег. Они ссылаются на предыдущее@param
.источник
@config
тега? Я не нашел ничего на usejsdoc.org , и эта страница предполагает,@config
что она устарела.@config
не рекомендуется на этом этапе. YUIDoc рекомендует использовать@attribute
вместо этого.