// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}
Ale jak opisać strukturę obiektów parametrów? Na przykład powinno to być coś takiego:
{
setting1 : 123, // (required, integer)
setting2 : 'asdf' // (optional, string)
}
javascript
jsdoc
Andy Hin
źródło
źródło
action
nazwy, piszę `foo = ({arg1, arg2, arg2}) => {...}`. Edycja: pytanie tutaj stackoverflow.com/questions/36916790/...Do tej pory istnieją 4 różne sposoby dokumentowania obiektów jako parametrów / typów. Każdy ma swoje własne zastosowania. Jednak tylko 3 z nich mogą być użyte do udokumentowania wartości zwracanych.
Dla obiektów o znanym zestawie właściwości (wariant A)
Ta składnia jest idealna dla obiektów, które są używane tylko jako parametry dla tej funkcji i nie wymagają dalszego opisu każdej właściwości. To może być stosowany do
@returns
tak dobrze .Dla obiektów o znanym zestawie właściwości (wariant B)
Bardzo przydatne są parametry ze składnią właściwości :
Ta składnia jest idealna dla obiektów, które są używane tylko jako parametry dla tej funkcji i które wymagają dalszego opisu każdej właściwości. Nie można tego użyć
@returns
.Dla obiektów, które będą używane w więcej niż jednym punkcie źródłowym
W tym przypadku @typedef jest bardzo przydatny. Można zdefiniować typ w jednym punkcie w źródle i użyć go jako typ dla
@param
lub@returns
lub innych znaczników JSDoc, które mogą skorzystać z typu.Następnie możesz użyć tego w
@param
tagu:Lub w
@returns
:Dla obiektów, których wartości są tego samego typu
Pierwszy typ (ciąg znaków) dokumentuje rodzaj kluczy, które w JavaScript zawsze są ciągiem lub przynajmniej zawsze będą wymuszone na ciąg. Drugi typ (liczba) to rodzaj wartości; może to być dowolny typ. Tej składni można również użyć
@returns
.Zasoby
Przydatne informacje na temat typów dokumentacji można znaleźć tutaj:
https://jsdoc.app/tags-type.html
PS:
aby udokumentować wartość opcjonalną, możesz użyć
[]
:lub:
źródło
{{dir: A|B|C }}
?{[myVariable]: string}
Widzę, że już istnieje odpowiedź na temat tagu @return, ale chcę podać więcej szczegółów na ten temat.
Po pierwsze, oficjalna dokumentacja JSDoc 3 nie podaje żadnych przykładów dotyczących @return dla obiektu niestandardowego. Proszę zobaczyć https://jsdoc.app/tags-returns.html . Zobaczmy teraz, co możemy zrobić, aż pojawi się jakiś standard.
Funkcja zwraca obiekt, w którym klucze są generowane dynamicznie. Przykład:
{1: 'Pete', 2: 'Mary', 3: 'John'}
. Zwykle iterujemy ten obiekt za pomocąfor(var key in obj){...}
.Możliwy JSDoc zgodnie z https://google.github.io/styleguide/javascriptguide.xml#JsTypes
Funkcja zwraca obiekt, w którym klucze są znanymi stałymi. Przykład:
{id: 1, title: 'Hello world', type: 'LEARN', children: {...}}
. Możemy łatwo uzyskać dostęp do właściwości tego obiektuobject.id
.Możliwy JSDoc według https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4
Sfałszuj to.
The Full Monty.
Zdefiniuj typ.
Według https://google.github.io/styleguide/javascriptguide.xml#JsTypes
Rodzaj rekordu.
źródło
Aby
@return
użyć tagu{{field1: Number, field2: String}}
, zobacz: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDocźródło
Źródło: JSDoc
źródło
W
@config
tych przypadkach jest nowy tag. Odnoszą się do poprzednich@param
.źródło
@config
znacznika? Nic nie znalazłem na usejsdoc.org , a ta strona sugeruje,@config
że jest przestarzała.@config
w tym momencie jest przestarzały. YUIDoc zaleca używanie@attribute
zamiast tego.