cách chính xác để ghi lại các chức năng lập luận mở trong JSDoc

Question

Hãy nói rằng bạn có một cái gì đó như sau:

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

Làm thế nào bạn sẽ ghi lại một cách chính xác rằng chức năng này có thể mất bất kỳ số lượng các đối số trong JSDoc? Đây là dự đoán tốt nhất của tôi, nhưng tôi không chắc nó là chính xác.

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

liên quan đến: php - How to doc a variable number of parameters

Answer 1

Các JSDoc specs và Google's Closure Compiler làm điều đó theo cách này:

@param {...number} var_args 

đâu "number" là kiểu lập luận mong đợi.

Việc sử dụng hoàn toàn này, sau đó, sẽ trông giống như sau:

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

Lưu ý những nhận xét về sử dụng arguments (hoặc một số offset của arguments) để truy cập đối số bổ sung của bạn. var_args nó chỉ được sử dụng để báo hiệu cho IDE của bạn rằng đối số thực sự tồn tại.

Rest parameters in ES6 có thể lấy tham số thực thêm một bước nữa để bao gồm các giá trị cung cấp (vì vậy không sử dụng nhiều hơn arguments là cần thiết):

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

Answer 2

Từ JSDoc users group:

Không có bất kỳ cách chính thức, nhưng một giải pháp khả thi là:

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

Các dấu ngoặc vuông cho biết một tham số tùy chọn, và ... sẽ (cho tôi) cho biết "một số số tùy ý."

Một khả năng khác là thế này ...

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

Dù bằng cách nào nên truyền đạt những gì bạn muốn nói.

Đó là một chút ngày, mặc dù (2007), nhưng tôi không biết gì hơn nữa.

Nếu bạn cần ghi lại loại tham số là 'hỗn hợp', hãy sử dụng {*}, như trong @param {*} [arguments].

Answer 3

Tôi đã tương tác với điều này trong một thời gian. Dưới đây là làm thế nào để làm điều đó với Google Closure Compiler:

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

Điều quan trọng là để cung cấp cho chức năng của bạn một tham số var_args (hoặc bất cứ điều gì bạn gọi nó trong bản Tuyên Bố @param của bạn) mặc dù chức năng không thực sự sử dụng tham số đó.

Answer 4

Cách thực hiện điều này là now described trong tài liệu JSDoc và nó sử dụng dấu ba chấm giống như tài liệu Đóng cửa.

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

Bạn cần cung cấp một loại đi sau khi lược, nhưng bạn có thể sử dụng một * để mô tả việc chấp nhận bất cứ điều gì, hoặc sử dụng các | để phân cách nhiều loại chấp nhận được. Trong tài liệu được tạo JSDoc sẽ mô tả đối số này là có thể lặp lại, giống như cách mô tả đối số tùy chọn là tùy chọn.

Trong thử nghiệm của mình, không cần phải có đối số trong định nghĩa hàm javascript thực tế, vì vậy mã thực sự của bạn chỉ có thể có dấu ngoặc đơn trống, tức là function whatever() { ... }.

loại đơn:

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

Bất kỳ loại (trong ví dụ dưới đây, các dấu ngoặc vuông có nghĩa items sẽ được gắn thẻ như cả hai tùy chọn và có thể lặp lại):

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

Nhiều loại cần ngoặc xung quanh danh sách loại, với dấu ba chấm trước dấu ngoặc mở:

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