Dokumentieren Sie den destruzierten Funktionsparameter in JSDoc

89

Bisher habe ich meine Objektparameter immer wie folgt dokumentiert:

/**
 * Description of the function
 *
 * @param {Object} config - The configuration
 * @param {String} config.foo
 * @param {Boolean} [config.bar] - Optional value
 * @return {String}
 */
function doSomething (config = {}) {
  const { foo, bar } = config;
  console.log(foo, bar);
  // do something
}

Ich bin mir jedoch nicht sicher, was der beste Ansatz für desstrukturierte Funktionsparameter ist. Ignoriere ich das Objekt einfach, definiere es irgendwie oder wie kann ich es am besten dokumentieren?

/**
 * Description of the function
 *
 * @param {String} foo
 * @param {Boolean} [bar] - Optional value
 * @return {String}
 */
function doSomething ({ foo, bar } = {}) {
  console.log(foo, bar);
  // do something
}

Ich habe das Gefühl, dass mein Ansatz oben nicht offensichtlich macht, dass die Funktion einen objectund nicht zwei verschiedene Parameter erwartet .

Eine andere Möglichkeit, die ich mir vorstellen könnte, wäre die Verwendung @typedef, aber das könnte ein großes Durcheinander sein (insbesondere in einer größeren Datei mit vielen Methoden)?

/**
 * @typedef {Object} doSomethingConfiguration
 * @property {String} foo
 * @property {Boolean} [bar] - Optional value
 */

/**
 * Description of the function
 *
 * @param {doSomethingConfiguration}
 * @return {String}
 */
function doSomething ({ foo, bar } = {}) {
  console.log(foo, bar);
  // do something
}
morkro
quelle
1
Ich denke, der erste Ansatz ist immer noch in Ordnung. Es interessiert niemanden, ob das Objekt configin Ihrem Code benannt ist oder überhaupt einen Namen hat.
Bergi
In WebStorm habe ich festgestellt, dass, wenn ich nur die Parameter (nach der Destrukturierung) beschreibe und die Destrukturierung ignoriere, dies meistens funktioniert, außer in weniger häufigen Fällen. Beschreiben Sie in Ihrem Beispiel zwei Parameter foound bar. Es ist keine endgültige Lösung, aber jeder Ansatz mit einem Objekt führte zu Inspektionsfehlern - und Inspektionen und automatische Vervollständigungen von der IDE sind mir am wichtigsten.
Mörre

Antworten:

96

So ist es beabsichtigt, wie in der Dokumentation beschrieben .

/**
 * My cool function.
 *
 * @param {Object} obj - An object.
 * @param {string} obj.prop1 - Property 1.
 * @param {string} obj.prop2 - Property 2.
 */
var fn = function ({prop1, prop2}) {
  // Do something with prop1 and prop2
}

Ihr erstes Beispiel ist also ziemlich richtig.

Ein weiteres Beispiel mit einer tieferen Verschachtelung:

/**
 * Nesting example.
 *
 * @param {object} param
 * @param {number} param.a - First value
 * @param {object} param.b - Wrapper
 * @param {number} param.b.c - Second value
 * @return {number} sum a and b
 */
letters = ({a, b: {c}}) => a + c;
Cerbrus
quelle
Ich sehe nicht, wie JSDoc eindeutig funktioniert, wenn Sie mehrere zerstörte Argumente haben, wie z function ({a}, {a}) {}. Das JSDoc würde ich wohl sein @param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.aund sich auf die Bestellung der @paramTags verlassen?
ZachB
@ZachB: function ({a}, {a}) {}ist ungültige Syntax, da adort zweimal definiert wird.
Cerbrus
1
Hoppla. ({a: b}, {a}))oder ({a}, {b})- Punkt war, dass JSDoc- @paramTags AFAIK ohne Ordnung sind und die Schlüssel mehrdeutig sein können, wenn JSDoc versucht, mithilfe von Eigenschaftsnamen eine Übereinstimmung herzustellen. Die nächste Version von VSCode verwendet die Positionssuche, um dieses Szenario zu beheben.
ZachB
1
Danke, @ d0gb3r7. Ich habe den Link in der Antwort aktualisiert.
Cerbrus
-8

Siehe JSDocs "Dokumentieren der Eigenschaften eines Parameters" :

/**
 * 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(employee) {
    // ...
};

(Die Überprüfung des Google Closure-Compilertyps , die auf JSDoc basiert, aber von JSDoc umgeleitet wurde, ermöglicht dies ebenfalls. @param {{x:number,y:number}} point A "point-shaped" object.)

Jakub Holý
quelle
2
Tut er das nicht schon? Er fragt, was zu tun ist, da employeedie Funktion keine Variable mehr enthält.
Bergi
7
Dies beantwortet die Frage nicht - in diesem Beispiel wird keine Destrukturierung verwendet! Bei der Destrukturierung haben Sie kein übergeordnetes Objekt.
Mörre
Eigentlich gibt sein gleicher Link direkt nach seinem Beispiel ein relatives Beispiel mit den gleichen exakten jsdoc-Kommentaren für Project.prototype.assign = function({ name, department }). Vor dem Beispiel heißt es: "Wenn ein Parameter ohne expliziten Namen zerstört wird, können Sie dem Objekt einen geeigneten Namen geben und seine Eigenschaften dokumentieren."
Notacouch