Wie beschreibe ich "Objekt" -Argumente in jsdoc?

316
// 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)
}
Andy Hin
quelle

Antworten:

428

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

Jonny Buchanan
quelle
17
Leider scheint das Retouren-Tag keinen äquivalenten Code
Michael Bylstra
1
In dieser ähnlichen Antwort stackoverflow.com/a/14820610/3094399 wurden am Anfang auch @param {Object} -Optionen hinzugefügt. Vermutlich ist es jedoch überflüssig.
pcatre
Haben Sie ein Beispiel für ES6-Destrukturierungsparameter? In meinem Fall habe ich den actionNamen nicht, ich schreibe `foo = ({arg1, arg2, arg2}) => {...}`. Bearbeiten: Frage hier stackoverflow.com/questions/36916790/…
Eric Burel
Haben Sie eine Idee, wie Sie ein Objektelement dokumentieren können? Ich meine, mein Benutzerobjekt sollte einen Benutzernamen haben und kann einen vollständigen Namen haben. Wie gebe ich an, dass der vollständige Name optional ist
Yash Kumar Verma
167

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
 */
Simon Zyx
quelle
Funktioniert die Variante 1 mit mehreren Arten einer Eigenschaft? Wie {{dir: A|B|C }}?
CMCDragonkai
Jede Art von Annotation sollte hier möglich sein, also ja
Simon Zyx
Und für Objekte, deren Schlüssel dynamisch generiert werden? Gefällt {[myVariable]: string}
mir
135

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 || {}
          }
      }
      
vogdb
quelle
Kennt jemand eine Möglichkeit, dies in IntelliJ / Webstorm zu generieren? Insbesondere spreche ich über die dritte Option - einen Typ definieren.
Erez Cohen
Bitte erläutern Sie. Möchten Sie einen Hotkey oder eine Verknüpfung in der IDE haben, um diese Dokumente zu generieren, oder möchten Sie, dass Ihre IDE diese Dokumente versteht? Vielleicht beide?
Vogdb
@vogdb Könnten Sie sich bitte dieses Problem ansehen? Ich glaube, dieser Anwendungsfall wird nicht mit Ihren großartigen Beispielen behandelt: stackoverflow.com/questions/53191739/…
Pavel Polyakov
@ PavelPolyakov Ich habe gesucht. Ich weiß wirklich nicht, wie ich Ihre Frage beantworten soll. Ich bin für eine Weile nicht bei JS. Fühlen Sie sich frei, meine Antwort zu bearbeiten, wenn Sie neue Informationen haben.
Vogdb
2

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

Karma Blackshaw
quelle
0

@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
 */
Mike DeSimone
quelle
1
Können Sie auf die Dokumentation für das @configTag verweisen ? Ich fand nichts auf usejsdoc.org , und diese Seite schlägt @configveraltet.
Dan Dascalescu
4
Ich denke, @configist an dieser Stelle veraltet. YUIDoc empfiehlt @attributestattdessen die Verwendung .
Mike DeSimone