Wie beschreibe ich "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 beschreibe ich, wie das Parameterobjekt strukturiert sein soll? Zum Beispiel sollte es so etwas sein wie:

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

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 wie folgt dokumentieren:

 /**
  * @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 ein @ config-Tag, das unmittelbar auf das entsprechende @ param folgte, aber es scheint veraltet zu sein ( Beispiel hier ).

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)

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

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 @returnsals auch .

Für Objekte mit bekannten Eigenschaften (Variante B)

Sehr nützlich sind die Parameter mit Eigenschaftensyntax :

/**
 * @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 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 @paramoder @returnsoder andere JSDoc Tags , die Verwendung von einer Art machen.

/**
 * @typedef {Object} Person
 * @property {string} name how the person is called
 * @property {number} age how many years the person lived
 */

Sie können dies dann in einem @paramTag verwenden:

/**
 * @param {Person} p - Description of p
 */

Oder in einem @returns:

/**
 * @returns {Person} Description
 */

Für Objekte, deren Werte alle vom gleichen Typ sind

/**
 * @param {Object.<string, number>} dict
 */

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 []:

/**
 * @param {number} [opt_number] this number is optional
 */

oder:

/**
 * @param {number|undefined} opt_number this number is optional
 */

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 Objekt for(var key in obj){...}.

  Mögliches JSDoc gemäß 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
  }
  

• 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.

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

  • Der volle 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);
    }
    

  • Definieren Sie einen Typ.

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

  • Der Datensatztyp.

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

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

Wenn erwartet wird, dass ein Parameter eine bestimmte Eigenschaft hat, können Sie diese Eigenschaft dokumentieren, indem Sie ein zusätzliches @ param-Tag angeben. Wenn beispielsweise erwartet wird, dass ein Mitarbeiterparameter Namen und Abteilungsmerkmale hat, können Sie dies wie folgt dokumentieren:

/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
function(employees) {
    // ...
}

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

/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

Quelle: JSDoc

@configFür diese Fälle gibt es ein neues Tag. Sie verlinken auf das Vorhergehende @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
 */