Cách đúng để ghi lại các hàm đối số kết thúc mở trong JSDoc

Giả sử 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 hàm này có thể nhận bất kỳ số đối số nào trong JSDoc? Đây là dự đoán tốt nhất của tôi, nhưng tôi không chắc nó chính xác.

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

Liên quan đến: php - Cách doc một số biến tham số

Các thông số kỹ thuật JSDoc và Trình biên dịch đóng cửa của Google thực hiện theo cách này:

@param {...number} var_args

Trong đó "số" là loại đối số được mong đợi.

Sau đó, cách sử dụng hoàn chỉnh của cái này sẽ giống như sau:

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

Lưu ý nhận xét về việc sử dụng arguments(hoặc một số bù đắp của arguments) để truy cập các đối số bổ sung của bạn. var_argsnó 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.

Tham số phần còn lại trong ES6 có thể đưa 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 cần sử dụng thêm arguments):

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

Cách thực hiện việc này hiện được mô tả trong tài liệu JSDoc và nó sử dụng dấu chấm lửng giống như tài liệu Closure.

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

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

Trong thử nghiệm của tôi, 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 tế của bạn có thể chỉ 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 nào (trong ví dụ bên dưới, dấu ngoặc vuông có nghĩa là itemssẽ được gắn thẻ là 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 có dấu ngoặc đơn quanh danh sách loại, với dấu chấm lửng trước dấu ngoặc mở đầu:

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

Từ nhóm người dùng JSDoc :

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

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

Dấu ngoặc vuông cho biết một tham số tùy chọn và ... sẽ (đối với tôi) chỉ ra "một số tùy ý."

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

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

Dù bằng cách nào cũng nên truyền đạt ý của bạn.

Mặc dù nó hơi cũ (2007), nhưng tôi không biết về bất cứ điều gì mới hơn.

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

Tôi đã tương lai với điều này trong một thời gian khá dài. Dưới đây là cách thực hiện với Trình biên dịch đóng cửa của Google:

/**
* @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 hàm của bạn một var_argstham số (hoặc bất cứ thứ gì bạn gọi nó trong @paramcâu lệnh của mình ) ngay cả khi hàm không thực sự sử dụng tham số đó.