JSDoc'ta açık uçlu bağımsız değişken işlevlerini belgelemenin doğru yolu

Aşağıdakine benzer bir şeye sahip olduğunuzu varsayalım:

var someFunc = function() {
    // do something here with arguments
}

Bu işlevin JSDoc'ta herhangi bir sayıda argüman alabileceğini nasıl doğru bir şekilde belgelersiniz? Bu benim en iyi tahminim ama doğru olduğundan emin değilim.

/**
 * @param {Mixed} [...] Unlimited amount of optional parameters
 */
var someFunc = function() {
    // do something here with arguments
}

İlgili: php - Değişken sayıda parametre nasıl belgelendirilir

JSDoc gözlük ve Google'ın Kapatma Derleyici bu şekilde yapın:

@param {...number} var_args

Burada "sayı", beklenen bağımsız değişkenlerin türüdür.

Bunun tam kullanımı şu şekilde görünecektir:

/**
* @param {...*} var_args
*/
function lookMaImVariadic(var_args) {
    // Utilize the `arguments` object here, not `var_args`.
}

Ek argümanlarınıza erişmek için kullanma arguments(veya ofsetinin bir kısmı arguments) hakkındaki yorumu not edin . var_argssadece IDE'nize argümanın gerçekten var olduğunu bildirmek için kullanılır.

ES6'daki dinlenme parametreleri , sağlanan değerleri kapsayacak şekilde gerçek parametreyi bir adım öteye taşıyabilir (bu nedenle, artık kullanılmasına argumentsgerek yoktur):

/**
* @param {...*} var_args
*/
function lookMaImES6Variadic(...var_args) {
    // Utilize the `var_args` array here, not `arguments`.
}

Bunun nasıl yapılacağı artık JSDoc belgelerinde açıklanmaktadır ve Kapanış belgelerinin yaptığı gibi bir üç nokta kullanır.

@param {...<type>} <argName> <Argument description>

Üç noktadan sonra gitmek için bir tür sağlamanız gerekir, ancak *herhangi bir şeyi kabul etmeyi açıklamak için a kullanabilir veya |kabul edilebilir birden çok türü ayırmak için kullanabilirsiniz . Oluşturulan belgelerde JSDoc bu bağımsız değişkeni, isteğe bağlı bağımsız değişkenleri isteğe bağlı olarak tanımladığı gibi tekrarlanabilir olarak tanımlayacaktır .

Testlerimde, gerçek javascript fonksiyon tanımında bir argümana sahip olmaya gerek yoktu, bu nedenle gerçek kodunuzda boş parantezler olabilir, yani function whatever() { ... }.

Tek tip:

@param {...number} terms Terms to multiply together

Herhangi bir tür (aşağıdaki örnekte, köşeli parantezlerin itemshem isteğe bağlı hem de tekrarlanabilir olarak etiketleneceği anlamına gelir ):

@param {...*} [items] - zero or more items to log.

Birden çok tür, tür listesi etrafında, üç nokta açılış parantezinden önce olacak şekilde parantez gerektirir:

@param {...(Person|string)} attendees - Meeting attendees, listed as either 
                                        String names or {@link Person} objects

Gönderen JSDoc kullanıcıları grubuna :

Resmi bir yol yok, ancak olası bir çözüm şudur:

/**
 * @param [...] Zero or more child nodes. If zero then ... otherwise ....
 */

Köşeli parantezler isteğe bağlı bir parametreyi belirtir ve ... işareti (bana göre) "bazı rastgele sayıları" gösterir.

Bir başka olasılık da bu ...

/**
 * @param [arguments] The child nodes.
 */

Her iki şekilde de ne demek istediğinizi iletmelisiniz.

Yine de biraz eski (2007), ancak daha güncel bir şeyin farkında değilim.

Eğer 'karışık', kullanımı gibi param türü belgelemek gerekiyorsa {*}olduğu gibi @param {*} [arguments].

Bir süre bununla uğraştım. Google Closure Compiler ile bunu şu şekilde yapabilirsiniz:

/**
* @param {...*} var_args
*/
function my_function(var_args) {
    // code that accesses the magic 'arguments' variable...
}

Önemli olan , işlev aslında o parametreyi kullanmasa bile , işlevinize bir var_argsparametre (veya @paramdeyiminizde onu ne adlandırırsanız) vermektir .