Wie beschreibt man "Objekt" Argumente in jsdoc?

//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 kann ich beschreiben, wie die Parameter-Objekts sollten strukturiert sein? Zum Beispiel sollte es etwas sein wie:

{
  setting1 : 123, //(required, integer)
  setting2 : 'asdf' //(optional, string)
}

InformationsquelleAutor der Frage Andy Hin | 2011-06-23

javascript jsdoc

291

Aus der @param wiki-Seite:

Parameter Mit Eigenschaften

Wenn ein parameter erwartet wird, haben eine Besondere Eigenschaft, Sie kann dokumentieren, dass sofort nach dem @param-tag für diesen parameter angeben, etwa so:
```
 /**
  * @param userInfo Information about the user.
  * @param userInfo.name The name of the user.
  * @param userInfo.email The email of the user.
  */
 function logIn(userInfo) {
        doLogIn(userInfo.name, userInfo.email);
 }
```
Früher gab es eine @config-tag, die sofort folgte die entsprechende @param, aber es scheint veraltet (Beispiel hier).

InformationsquelleAutor der Antwort Jonny Buchanan

110

Sehe ich, dass es bereits eine Antwort auf die Frage der @return-tag, aber ich wollen, um mehr details zu erfahren.

Zuerst von allen, ist die offizielle JSDoc 3 Dokumentation gibt uns nicht irgendwelche Beispiele, über die @return für ein benutzerdefiniertes Objekt. Bitte sehen http://usejsdoc.org/tags-returns.html. Nun, lasst uns sehen, was wir tun können, bis einige standard wird angezeigt.

Funktion Objekt gibt, wo die Tasten sind dynamisch generiert. Beispiel: {1: 'Pete', 2: 'Mary', 3: 'John'}. In der Regel, wir iterieren über dieses Objekt mit Hilfe von for(var key in obj){...}.

Möglich JSDoc nach 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
}
```

Funktion Objekt gibt, wo die Tasten sind bekannte Konstanten. Beispiel: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Wir können leicht auf die Eigenschaften dieses Objekts: object.id.

Möglich JSDoc nach https://groups.google.com/forum/#!Thema/jsdoc-Benutzer/TMvUedK9tC4

Fake.

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

The Full Monty.

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

Einen Typ definieren.

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

Laut https://google.github.io/styleguide/javascriptguide.xml#JsTypes

Den Datensatz-Typ.

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

InformationsquelleAutor der Antwort vogdb

74

Mittlerweile gibt es 4 verschiedene Möglichkeiten, um Dokument-Objekte als Parameter/Typen. Jeder hat seine eigenen verwendet. Nur 3 von Ihnen können verwendet werden, um Dokument-Werte zurückgeben, wenn.

Für Objekte mit einem bekannten Satz von Eigenschaften (Variante A)
```
/**
 * @param {{a: number, b: string, c}} myObj description
 */
```
Diese syntax ist ideal für Objekte, die verwendet werden, nur als Parameter für diese Funktion und erfordern keine weitere Beschreibung der einzelnen-Eigenschaft.
Es kann verwendet werden, für die @returns als auch.

Für Objekte mit einem bekannten Satz von Eigenschaften (Variante B)

Sehr nützlich ist die Parameter, die mit den Eigenschaften syntax:
```
/**
 * @param {Object} myObj description
 * @param {number} myObj.a description
 * @param {string} myObj.b description
 * @param {} myObj.c description
 */
```
Diese syntax ist ideal für Objekte, die verwendet werden, nur als Parameter für diese Funktion, und das erfordert eine weitere Beschreibung der einzelnen-Eigenschaft.
Dies kann nicht verwendet werden @returns.

Für Objekte, die verwendet werden, an mehr als einer Stelle in der Quelle

In diesem Fall eine @typedef in sehr handliches kommt. Sie definieren die Art an einer Stelle in Ihrer Quelle und verwenden Sie es als eine Art für @param oder @returns oder andere JSDoc-tags, die können machen, verwenden Sie einen Typ aus.
```
/**
 * @typedef {Object} Person
 * @property {string} name how the person is called
 * @property {number} age how many years the person lived
 */
```
Anschließend können Sie diese in einem @param tag:
```
/**
 * @param {Person} p - Description of p
 */
```
Für Objekte, deren Werte sind alle vom gleichen Typ
```
/**
 * @param {Object.<string, number>} dict
 */
```
Des ersten Typs (string) Dokumente, die den Typ der keys, die in JavaScript immer einen string oder zumindest immer dazu gezwungen einen string. Der zweite Typ (Nummer) ist der Typ des Werts; dies kann ein beliebiger Typ.
Diese syntax kann verwendet werden, für @returns als gut.

Ressourcen

Nützliche Informationen zu dokumentieren-Typen finden Sie hier:

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

PS:

Dokument ein optionaler Wert, den Sie verwenden können, []:
```
/**
 * @param {number} [opt_number] this number is optional
 */
```
oder:
```
/**
 * @param {number|undefined} opt_number this number is optional
 */
```
InformationsquelleAutor der Antwort Simon Zyx
16

Für @return tag verwenden {{field1: Number, field2: String}} finden Sie unter: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+mit+JSDoc

InformationsquelleAutor der Antwort maliboo

Gibt es eine neue @config tag für diese Fälle. Die Verknüpfung zu den vorhergehenden @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
 */

InformationsquelleAutor der Antwort Mike DeSimone

Schreibe einen Kommentar

Du musst angemeldet sein, um einen Kommentar abzugeben.

Parameter Mit Eigenschaften