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 object
und 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
}
config
in Ihrem Code benannt ist oder überhaupt einen Namen hat.foo
undbar
. 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.Antworten:
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;
quelle
function ({a}, {a}) {}
. Das JSDoc würde ich wohl sein@param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.a
und sich auf die Bestellung der@param
Tags verlassen?function ({a}, {a}) {}
ist ungültige Syntax, daa
dort zweimal definiert wird.({a: b}, {a}))
oder({a}, {b})
- Punkt war, dass JSDoc-@param
Tags 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.Ich persönlich benutze dieses:
/** * @param {{ a: number b: number }} param0 * @returns {number} The sum */ const func = ({ a, b }) => a + b;
Erstellen Sie einfach das Objekt genau dort.
Ich nutze auch TypeScript und würde es
b
alsb?
oderb: number | undefined
als JSDoc deklarieren, das auch Gewerkschaften zulässtquelle
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.
)quelle
employee
die Funktion keine Variable mehr enthält.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."