Bir argüman listesi, bilinen parametre türleriyle değişken uzunluklu olarak nasıl belgelenir?

Question

İlgili: Correct way to document open-ended argument functions in JSDoc

Ben arguments değişken erişerek çoklu diziler kabul eden bir işlev ettik: Ben options yanında her argüman değerinde belgeleyen olan değerleri içeren bir dizidir olduğunu Şimdi

/** 
* @param options An object containing options 
* @param [options.bind] blablabla (optional) 
*/ 
function modify_function (options) { 
    for (var i=1; i<arguments.length; i++) { 
     // ... 
    } 
} 

biliyorum:

[search_term, replacement, options] 

Değişken parametre satırında (uzun) açıklamayı koymayı düşünmüyorum.

@param {...} Arama terimleri, değiştirmeler ve seçeneklerine sahip bir dizi; dizin 0: fonksiyon içindeki arama terimi; 1: yedek metin; 2: İsteğe bağlı seçenekler (catch_errors: yakalar hataları ve bunu günlük kaçış:, yedek metninde pos dolar kaçış: sonrasına yerleştirmekten için arama terimi, "R" den önce değiştirilmesini yerleştirmek için "L") okunabilir bir çözüm değil ve tür görünür değil.

Bir değişken parametresinin türlerini ve değerlerini belgelemenin bir yolu var mı?

@param {...[]} An array with search terms, replacements and its options 
@param {...[0]} The search term within the function 
@param {...[1]} The replacement text 
@param {...[2]} An optional object with obtions for the replacement 
@param {...[2].catch_errors} catches errors and log it 
@param {...[2].escape} etc... 

yukarıda çirkin görünüyor, ama sana ulaşmak için çalışıyorum bir fikir vermelidir:

• belgesini (bu durumda Dizi) değişken parametrenin tipi
• belge bu dizide
• belge bu dizinin tembellik için

içindeki bir nesnenin özelliklerini nasıl yaptığınızı kullanım değerleri d bir nesne yerine bir dizi. Diğer öneriler her zaman beklerim.

Answer 1

Örneğin İşleviniz gerçekten değişken argümanlar değil, sadece imzayı öneren şeyin önerilerine göre değiştirmelisiniz.O JSDoc foundrama biraz daha iyi sözdizimi

/** 
* @param {String} searchTerm 
* @param {String} replacementText 
* @param {Object} opts (optional) An object containing the replacement options 
* @param {Function} opts.catch_errors Description text 
* @param {Event} opts.catch_errors.e The name of the first parameter 
*   passed to catch_errors 
* @param {Type} opts.escape Description of options 
*/ 

önerdi Ve

gerçekten varargs stili için bir durum var yaparsanız

modify_text('search', 'replacement', { 
    catch_errors: function(e) { 

    }, 
    escape: 'someEscape' 

}); 

gibi derdim etmiştir dışında, bir değişken olmalıdır bir JSDoc standart olmasa parametre listesinin sonunda geçirilebilir aynı tip, ben * 0, 1 endeksli düşünmek Google'ın kendi belgelerinde

/** 
* Sums its parameters 
* @param {...number} var_args Numbers to be added together 
* @return number 
*/ 
function sum(/* num, num, ... */) { 
    var sum = 0; 
    for (var i =0; i < arguments.length; i++) { 
     sum += arguments[i]; 
    } 
    return sum; 
} 

Answer 2

Başka bir API tarafından kısıtlanmadıkça, öneride bulunacağım ilk şey: , yinelemeyi amaçladığınız bir veri toplama dışında herhangi bir şey için bir dizi kullanmaz.

Muhtemelen burada en iyi yaklaşım üç parametre veya başka param nesnesi çeşit alır, öyle ki işlevini faktörlü yeniden olacaktır.

/** 
* @param {String} searchTerm 
* @param {String} replacementText 
* @param {Object} replacementOpts (optional) An object containing the replacement 
* options; optional values in the object include:<ul> 
    <li>catch_errors {Type} description text...</li> 
    <li>escape {Type} description text...</li></ul> 
*/ 

şiddetle (tekrar: "Eğer sizin kontrolünüz dışında bazı API tarafından sınırlanmış sürece) dizisi kullanarak karşı tavsiye

:. O kırılgan ve sonuçta biraz kafa hem ispat edecek şekilde