Dokument zniszczony parametr funkcji w JSDoc

89

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 objectróż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
}
morkro
źródło
1
Myślę, że pierwsze podejście jest nadal w porządku. Nikt nie dba o to, czy obiekt jest nazwany configw Twoim kodzie, czy też ma jakąkolwiek nazwę.
Bergi
W WebStorm odkryłem, że jeśli tylko opiszę parametry (po destrukturyzacji) i zignoruję destrukturyzację, to działa to głównie z wyjątkiem mniej powszechnych przypadków. W swoim przykładzie opisz dwa parametry fooi bar. 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.
Mörre,

Odpowiedzi:

96

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;
Cerbrus
źródło
Nie rozumiem, jak jednoznacznie działa JSDoc, gdy masz wiele zniszczonych argumentów, takich jak function ({a}, {a}) {}. Wydaje mi się, że JSDoc byłby @param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.ai polegałby na kolejności @paramtagów?
ZachB
@ZachB: function ({a}, {a}) {}ma nieprawidłową składnię, ponieważ ajest tam zdefiniowana dwukrotnie.
Cerbrus
1
Ups. ({a: b}, {a}))lub ({a}, {b})- chodziło o to, że @paramznaczniki 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.
ZachB
1
Dzięki, @ d0gb3r7. Zaktualizowałem link w odpowiedzi.
Cerbrus
8

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 bjako b?lub b: number | undefinedjako JSDoc pozwala również związki

Kodowanie Edgara
źródło
-8

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

Jakub Holý
źródło
2
Czy on już tego nie robi? Pyta, co zrobić teraz, gdy employeew funkcji nie ma już zmiennej.
Bergi
7
To nie odpowiada na pytanie - w tym przykładzie nie zastosowano destrukturyzacji! W przypadku destrukturyzacji nie masz obiektu nadrzędnego.
Mörre,
Właściwie to ten sam link, zaraz po jego przykładzie, podaje relatywny przykład z tymi samymi dokładnymi komentarzami w jsdoc dla 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”.
notacouch