JSDoc'ta bozulmuş işlev parametresini belgeleyin


90

Daha önce nesne parametrelerimi her zaman aşağıdaki gibi belgelemiştim:

/**
 * 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
}

Ancak, yapılandırılmış fonksiyon parametresiyle en iyi yaklaşımın ne olduğundan emin değilim. Nesneyi görmezden mi geliyor, bir şekilde tanımlıyor muyum yoksa onu belgelemenin en iyi yolu nedir?

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

Yukarıdaki yaklaşımımın, işlevin objectiki farklı parametre beklemediğini açıkça belirtmediğini hissediyorum .

Düşünebileceğim başka bir yol kullanmak @typedefolabilir, ancak bu büyük bir karmaşa haline gelebilir (özellikle birçok yöntem içeren daha büyük bir dosyada)?

/**
 * @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
}

1
İlk yaklaşımın hala iyi olduğunu düşünüyorum. Nesnenin configkodunuzda adlandırılıp adlandırılmadığı veya herhangi bir adı olup olmadığı kimsenin umurunda değil .
Bergi

WebStorm'da, (imha sonrası) parametreleri açıklarsam ve yok etmeyi görmezden gelirsem, daha az yaygın durumlar dışında çoğunlukla işe yaradığını buldum. Öyleyse örneğinizde iki parametreyi tanımlayın foove bar. Bu nihai bir çözüm değil, ancak bir nesneyi kullanan herhangi bir yaklaşım denetim hatalarına yol açtı - ve IDE'den denetimler ve otomatik tamamlamalar en çok önemsediğim şeydi.
Mörre

Yanıtlar:


96

Dokümantasyonda açıklandığı gibi bu şekilde tasarlanmaktadır .

/**
 * 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
}

Yani, ilk örneğiniz oldukça doğru.

Daha derin yuvalama ile başka bir örnek:

/**
 * 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;

Birden fazla yıkılmış argümanınız olduğunda JSDoc'un açık bir şekilde nasıl çalıştığını anlamıyorum function ({a}, {a}) {}. JSDoc sanırım olacak @param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.ave @parametiketlerin sırasına mı bağlı?
ZachB

@ZachB: orada iki kez tanımlandığından function ({a}, {a}) {}geçersiz sözdizimi a.
Cerbrus

1
Oops. ({a: b}, {a}))veya ({a}, {b})- nokta, JSDoc @parametiketlerinin sırasız AFAIK olması ve anahtarların özellik adlarını kullanarak eşleştirmeye çalışmak için JSDoc gibi belirsiz olabilmesiydi. VSCode'un bir sonraki sürümü, bu senaryoyu çözmek için konumsal aramayı kullanacak.
ZachB

1
Teşekkürler @ d0gb3r7. Yanıttaki bağlantıyı güncelledim.
Cerbrus


-8

JSDoc'un "Bir parametrenin özelliklerini belgeleme" bölümüne bakın :

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

( JSDoc'a dayanan ancak ondan yönlendirilen Google Closure derleyici türü denetimi de izin verir @param {{x:number,y:number}} point A "point-shaped" object.)


2
Bunu zaten yapmıyor mu? Artık employeefonksiyonda değişken olmadığına göre şimdi ne yapacağını soruyor .
Bergi

7
Bu soruya cevap vermiyor - bu örnek yıkımı kullanmıyor! Yıkımla ana nesneniz olmaz.
Mörre

Aslında aynı bağlantısı, örneğinden hemen sonra, aynı jsdoc yorumlarına sahip göreli bir örnek veriyor Project.prototype.assign = function({ name, department }). Örnekten önce, "Bir parametre açık bir ad olmadan yok edilirse, nesneye uygun bir tane verebilir ve özelliklerini belgeleyebilirsiniz" derler.
notacouch
Sitemizi kullandığınızda şunları okuyup anladığınızı kabul etmiş olursunuz: Çerez Politikası ve Gizlilik Politikası.
Licensed under cc by-sa 3.0 with attribution required.