Làm cách nào để ghi lại danh sách đối số có độ dài thay đổi với các loại tham số đã biết?

Question

liên quan: Correct way to document open-ended argument functions in JSDoc

Tôi đã một chức năng mà chấp nhận nhiều mảng bằng cách truy cập arguments biến:

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

Bây giờ, tôi biết rằng mỗi đối số bên cạnh options là một mảng chứa giá trị mà có giá trị chủ tài liệu:

[search_term, replacement, options] 

Tôi không cân nhắc đưa mô tả (dài) vào dòng thông số biến.

@param {...} Một mảng có cụm từ tìm kiếm, thay thế và tùy chọn của nó; chỉ mục 0: cụm từ tìm kiếm trong hàm; 1: văn bản thay thế; 2: tùy chọn tùy chọn (catch_errors: bắt lỗi và đăng nhập, thoát: thoát đô la trong văn bản thay thế, đặt: "L" để đặt thay thế trước cụm từ tìm kiếm "R" để đặt sau) Không phải giải pháp có thể đọc được loại không hiển thị.

Có cách nào để ghi lại các loại và giá trị của thông số biến không?

@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... 

Trên đây trông xấu xí, nhưng nó sẽ cho bạn một ý tưởng về những gì tôi đang cố gắng để đạt được:

• tài liệu loại một tham số biến (trong trường hợp này một mảng)
• tài liệu các giá trị của mảng này
• tài liệu các thuộc tính của một đối tượng trong mảng này

Đối với sự lười biếng, tôi đã sử dụng d một mảng thay vì một đối tượng. Các đề xuất khác luôn được chào đón.

Answer 1

Hàm của bạn không thực sự là đối số biến, bạn chỉ nên thay đổi chữ ký của nó thành những gì mà foundrama đề xuất.Trừ JSDoc đó có cú pháp tốt hơn một chút so với foundrama gợi ý

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

Và bạn muốn gọi nó như

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

    }, 
    escape: 'someEscape' 

}); 

Nếu bạn thực sự không có một trường hợp cho phong cách varargs, nó phải là một biến của cùng loại có thể được chuyển vào cuối danh sách tham số, tôi ghi lại nó như sau, mặc dù đó không phải là tiêu chuẩn JSDoc, đó là những gì Google sử dụng với tài liệu của họ

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

Trừ khi bạn bị hạn chế bởi một số API khác, thì điều đầu tiên tôi đề xuất là: không sử dụng mảng cho bất kỳ thứ gì ngoại trừ bộ sưu tập dữ liệu bạn định lặp lại.

Có lẽ cách tiếp cận tốt nhất ở đây sẽ là tái xác định hàm như vậy mà phải mất ba tham số hoặc một số loại đối tượng param khác. Ví dụ:

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

tôi khuyên chống lại bằng cách sử dụng mảng (một lần nữa: "trừ khi bạn đang bị chặn bởi một số API ngoài tầm kiểm soát của bạn). Vì nó sẽ chứng minh tất cả giòn và cuối cùng là một chút bối rối