Wie beschreibt man "Object"-Argumente in jsdoc?

Question

// Meine Funktion macht X und Y.
// @params {object} parameters Ein Objekt, das die Parameter enthält
// @params {function} callback Die Rückruffunktion
function(parameters, callback) {
}

Aber wie beschreibe ich, wie das Parameterobjekt strukturiert sein sollte? Zum Beispiel sollte es so aussehen:

{
  setting1 : 123, // (erforderlich, Ganzzahl)
  setting2 : 'asdf' // (optional, Zeichenkette)
}

Answer 1

Von der @param Wiki-Seite:

---

Parameter mit Eigenschaften

Wenn erwartet wird, dass ein Parameter eine bestimmte Eigenschaft hat, können Sie dies unmittelbar nach dem @param-Tag für diesen Parameter dokumentieren, wie folgt:

 /**
  * @param userInfo Informationen über den Benutzer.
  * @param userInfo.name Der Name des Benutzers.
  * @param userInfo.email Die E-Mail des Benutzers.
  */
 function logIn(userInfo) {
        doLogIn(userInfo.name, userInfo.email);
 }

---

Früher gab es ein @config-Tag, das unmittelbar nach dem entsprechenden @param-Tag stand, aber anscheinend wurde es deprecated (Beispiel hier).

Answer 2

Bis jetzt gibt es 4 verschiedene Möglichkeiten, Objekte als Parameter/Typen zu dokumentieren. Jede hat ihre eigenen Verwendungszwecke. Nur 3 davon können jedoch zur Dokumentation von Rückgabewerten verwendet werden.

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

/**
 * @param {{a: number, b: string, c}} myObj Beschreibung
 */

Dies ist ideal für Objekte, die nur als Parameter für diese Funktion verwendet werden und keine weitere Beschreibung jeder Eigenschaft erfordern. Es kann auch für @returns verwendet werden.

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

Sehr nützlich ist die Syntax Parameter mit Eigenschaften:

/**
 * @param {Object} myObj Beschreibung
 * @param {number} myObj.a Beschreibung
 * @param {string} myObj.b Beschreibung
 * @param {} myObj.c Beschreibung
 */

Diese Syntax ist ideal für Objekte, die nur als Parameter für diese Funktion verwendet werden und eine weitere Beschreibung jeder Eigenschaft erfordern. Dies kann nicht für @returns verwendet werden.

Für Objekte, die an mehreren Stellen im Quellcode verwendet werden

In diesem Fall ist ein @typedef sehr nützlich. Sie können den Typ an einer Stelle in Ihrem Quellcode definieren und ihn als Typ für @param oder @returns oder andere JSDoc-Tags verwenden, die einen Typ verwenden können.

/**
 * @typedef {Object} Person
 * @property {string} name wie die Person genannt wird
 * @property {number} age wie viele Jahre die Person gelebt hat
 */

Sie können dies dann in einem @param Tag verwenden:

/**
 * @param {Person} p - Beschreibung von p
 */

Oder in einem @returns:

/**
 * @returns {Person} Beschreibung
 */

Für Objekte, deren Werte alle denselben Typ haben

/**
 * @param {Object.} dict
 */

Der erste Typ (string) dokumentiert den Typ der Schlüssel, der in JavaScript immer eine Zeichenfolge ist oder zumindest immer zu einer Zeichenfolge gezwungen wird. Der zweite Typ (number) ist der Typ des Werts; dies kann jeder Typ sein. Diese Syntax kann auch für @returns verwendet werden.

Ressourcen

Nützliche Informationen zum Dokumentieren von Typen finden Sie hier:

https://jsdoc.app/tags-type.html

PS:

Um einen optionalen Wert zu dokumentieren, können Sie [] verwenden:

/**
 * @param {number} [opt_number] Diese Zahl ist optional
 */

oder:

/**
 * @param {number|undefined} opt_number Diese Zahl ist optional
 */

Answer 3

Ich sehe, dass es bereits eine Antwort zum @return-Tag gibt, aber ich möchte weitere Details dazu geben.

Zunächst einmal gibt uns die offizielle JSDoc 3-Dokumentation keine Beispiele für das @return für ein benutzerdefiniertes Objekt. Bitte siehe https://jsdoc.app/tags-returns.html. Jetzt sehen wir, was wir tun können, bis ein Standard erscheint.

• Funktion gibt ein Objekt zurück, dessen Schlüssel dynamisch generiert werden. Beispiel: {1: 'Pete', 2: 'Mary', 3: 'John'}. Normalerweise iterieren wir über dieses Objekt mit Hilfe von for(var key in obj){...}.

  Mögliche JSDoc gemäß https://google.github.io/styleguide/javascriptguide.xml#JsTypes

  /**
   * @return {Object.}
   */
  function getTmpObject() {
      var result = {}
      for (var i = 10; i >= 0; i--) {
          result[i * 3] = 'someValue' + i;
      }
      return result
  }

• Funktion gibt ein Objekt zurück, dessen Schlüssel bekannte Konstanten sind. Beispiel: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Wir können leicht auf die Eigenschaften dieses Objekts zugreifen: object.id.

  Mögliche JSDoc gemäß https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

  • Fake It.

    /**
     * Generiere einen Punkt.
     *
     * @returns {Object} point - Der vom Factory generierte Punkt.
     * @returns {number} point.x - Die x-Koordinate.
     * @returns {number} point.y - Die y-Koordinate.
     */
    var pointFactory = function (x, y) {
        return {
            x:x,
            y:y
        }
    }

  • The Full Monty.

    /**
     @class generatedPoint
     @private
     @type {Object}
     @property {number} x Die x-Koordinate.
     @property {number} y Die y-Koordinate.
     */
    function generatedPoint(x, y) {
        return {
            x:x,
            y:y
        };
    }
    
    /**
     * Generiere einen Punkt.
     *
     * @returns {generatedPoint} Der vom Factory generierte Punkt.
     */
    
    var pointFactory = function (x, y) {
        return new generatedPoint(x, y);
    }

  • Definiere einen Typ.

    /**
     @typedef generatedPoint
     @type {Object}
     @property {number} x Die x-Koordinate.
     @property {number} y Die y-Koordinate.
     */
    
    /**
     * Generiere einen Punkt.
     *
     * @returns {generatedPoint} Der vom Factory generierte Punkt.
     */
    
    var pointFactory = function (x, y) {
        return {
            x:x,
            y:y
        }
    }

  Gemäß https://google.github.io/styleguide/javascriptguide.xml#JsTypes

  • Der Datensatztyp.

    /**
     * @return {{myNum: number, myObject}}
     * Ein anonymer Typ mit den angegebenen Typmembern.
     */
    function getTmpObject() {
        return {
            myNum: 2,
            myObject: 0 || undefined || {}
        }
    }

Answer 4

Für das @return-Tag verwenden Sie {{field1: Number, field2: String}}, siehe: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

Answer 5

Wenn erwartet wird, dass ein Parameter eine bestimmte Eigenschaft hat, können Sie diese Eigenschaft dokumentieren, indem Sie einen zusätzlichen @param-Tag angeben. Wenn beispielsweise erwartet wird, dass ein Mitarbeiterparameter die Eigenschaften Name und Abteilung hat, können Sie ihn wie folgt dokumentieren:

/**
 * Weisen Sie das Projekt einer Liste von Mitarbeitern zu.
 * @param {Object[]} employees - Die Mitarbeiter, die für das Projekt verantwortlich sind.
 * @param {string} employees[].name - Der Name eines Mitarbeiters.
 * @param {string} employees[].department - Die Abteilung des Mitarbeiters.
 */
function(employees) {
    // ...
}

Wenn ein Parameter ohne expliziten Namen destrukturiert wird, können Sie dem Objekt einen passenden Namen geben und seine Eigenschaften dokumentieren.

/**
 * Weisen Sie das Projekt einem Mitarbeiter zu.
 * @param {Object} employee - Der Mitarbeiter, der für das Projekt verantwortlich ist.
 * @param {string} employee.name - Der Name des Mitarbeiters.
 * @param {string} employee.department - Die Abteilung des Mitarbeiters.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

Quelle: JSDoc