Wcześniej zawsze dokumentowałem parametry mojego obiektu w następujący sposób:
/**
* 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
}
Ale nie jestem pewien, jakie jest najlepsze podejście z opisanym parametrem funkcji. Czy po prostu ignoruję obiekt, jakoś go definiuję, czy też jak najlepiej go udokumentować?
/**
* Description of the function
*
* @param {String} foo
* @param {Boolean} [bar] - Optional value
* @return {String}
*/
function doSomething ({ foo, bar } = {}) {
console.log(foo, bar);
// do something
}
Wydaje mi się, że moje podejście powyżej nie wskazuje na to, że funkcja oczekuje object
różnych parametrów, a nie dwóch.
Innym sposobem, o którym mógłbym pomyśleć, byłby użycie @typedef
, ale może to skończyć się ogromnym bałaganem (szczególnie w większym pliku z wieloma metodami)?
/**
* @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
w Twoim kodzie, czy też ma jakąkolwiek nazwę.foo
ibar
. To nie jest ostateczne rozwiązanie, ale każde podejście z użyciem obiektu powodowało błędy inspekcji - a inspekcje i autouzupełnianie z IDE są tym, na czym najbardziej mi zależy.Odpowiedzi:
Jest to zamierzone, zgodnie z opisem w dokumentacji .
/** * 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 }
Więc twój pierwszy przykład jest prawie poprawny.
Inny przykład z głębszym zagnieżdżeniem:
/** * 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;
źródło
function ({a}, {a}) {}
. Wydaje mi się, że JSDoc byłby@param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.a
i polegałby na kolejności@param
tagów?function ({a}, {a}) {}
ma nieprawidłową składnię, ponieważa
jest tam zdefiniowana dwukrotnie.({a: b}, {a}))
lub({a}, {b})
- chodziło o to, że@param
znaczniki JSDoc są bez kolejności AFAIK, a klucze mogą być niejednoznaczne, gdyby JSDoc próbowała dopasować za pomocą nazw właściwości. Następna wersja VSCode będzie używać wyszukiwania pozycyjnego do rozwiązania tego scenariusza.Osobiście używam tego:
/** * @param {{ a: number b: number }} param0 * @returns {number} The sum */ const func = ({ a, b }) => a + b;
Po prostu stwórz obiekt właśnie tam.
Ja również wykorzystać maszynopis , i deklarują obtional
b
jakob?
lubb: number | undefined
jako JSDoc pozwala również związkiźródło
Zobacz „Dokumentowanie właściwości parametru” JSDoc :
/** * 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) { // ... };
( Sprawdzanie typu kompilatora Google Closure , które zostało oparte na JSDoc, ale zostało z niego przekierowane, również pozwala
@param {{x:number,y:number}} point A "point-shaped" object.
)źródło
employee
w funkcji nie ma już zmiennej.Project.prototype.assign = function({ name, department })
. Przed przykładem mówią: „Jeśli parametr zostanie zniszczony bez wyraźnej nazwy, możesz nadać obiektowi odpowiednią i udokumentować jego właściwości”.