// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}
Aber wie beschreibe ich, wie das Parameterobjekt strukturiert sein soll? Zum Beispiel sollte es so etwas sein wie:
{
setting1 : 123, // (required, integer)
setting2 : 'asdf' // (optional, string)
}
javascript
jsdoc
Andy Hin
quelle
quelle
action
Namen nicht, ich schreibe `foo = ({arg1, arg2, arg2}) => {...}`. Bearbeiten: Frage hier stackoverflow.com/questions/36916790/…Inzwischen gibt es 4 verschiedene Möglichkeiten, Objekte als Parameter / Typen zu dokumentieren. Jeder hat seine eigenen Verwendungen. Nur 3 davon können jedoch zur Dokumentation von Rückgabewerten verwendet werden.
Für Objekte mit bekannten Eigenschaften (Variante A)
Diese Syntax ist ideal für Objekte, die nur als Parameter für diese Funktion verwendet werden und keine weitere Beschreibung jeder Eigenschaft erfordern. Es kann verwendet werden
@returns
als auch .Für Objekte mit bekannten Eigenschaften (Variante B)
Sehr nützlich sind die Parameter mit Eigenschaftensyntax :
Diese Syntax ist ideal für Objekte, die nur als Parameter für diese Funktion verwendet werden und für die eine weitere Beschreibung der einzelnen Eigenschaften erforderlich ist. Dies kann nicht für verwendet werden
@returns
.Für Objekte, die an mehr als einem Punkt in der Quelle verwendet werden
In diesem Fall ist ein @typedef sehr praktisch. Sie können den Typen an einem Punkt in Ihrer Quelle definieren und verwenden Sie es als eine Art für
@param
oder@returns
oder andere JSDoc Tags , die Verwendung von einer Art machen.Sie können dies dann in einem
@param
Tag verwenden:Oder in einem
@returns
:Für Objekte, deren Werte alle vom gleichen Typ sind
Der erste Typ (Zeichenfolge) dokumentiert den Typ der Schlüssel, der in JavaScript immer eine Zeichenfolge ist oder zumindest immer zu einer Zeichenfolge gezwungen wird. Der zweite Typ (Nummer) ist der Typ des Werts; Dies kann ein beliebiger Typ sein. Diese Syntax kann auch für verwendet werden
@returns
.Ressourcen
Nützliche Informationen zu Dokumentationsarten finden Sie hier:
https://jsdoc.app/tags-type.html
PS:
Um einen optionalen Wert zu dokumentieren, können Sie Folgendes verwenden
[]
:oder:
quelle
{{dir: A|B|C }}
?{[myVariable]: string}
Ich sehe, dass es bereits eine Antwort zum @ return-Tag gibt, aber ich möchte mehr Details dazu geben.
Erstens enthält die offizielle JSDoc 3-Dokumentation keine Beispiele für die @ Rückgabe für ein benutzerdefiniertes Objekt. Weitere Informationen finden Sie unter https://jsdoc.app/tags-returns.html . Nun wollen wir sehen, was wir tun können, bis ein Standard erscheint.
Die Funktion gibt ein Objekt zurück, bei dem Schlüssel dynamisch generiert werden. Beispiel :
{1: 'Pete', 2: 'Mary', 3: 'John'}
. Normalerweise iterieren wir mit Hilfe von über dieses Objektfor(var key in obj){...}
.Mögliches JSDoc gemäß https://google.github.io/styleguide/javascriptguide.xml#JsTypes
Die Funktion gibt ein Objekt zurück, bei dem Schlüssel bekannte Konstanten sind. Beispiel :
{id: 1, title: 'Hello world', type: 'LEARN', children: {...}}
. Wir können leicht auf Eigenschaften dieses Objekts zugreifen :object.id
.Mögliches JSDoc gemäß https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4
Fälsche es.
Der volle Monty.
Definieren Sie einen Typ.
Laut https://google.github.io/styleguide/javascriptguide.xml#JsTypes
Der Datensatztyp.
quelle
Für
@return
Tag Verwendung{{field1: Number, field2: String}}
finden Sie unter : http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDocquelle
Quelle: JSDoc
quelle
@config
Für diese Fälle gibt es ein neues Tag. Sie verlinken auf das Vorhergehende@param
.quelle
@config
Tag verweisen ? Ich fand nichts auf usejsdoc.org , und diese Seite schlägt@config
veraltet.@config
ist an dieser Stelle veraltet. YUIDoc empfiehlt@attribute
stattdessen die Verwendung .