Chức năng gọi lại bình luận

Question

Chỉ cần tò mò một cách tốt để bình luận thông số nào sẽ được chuyển đến hàm gọi lại.

Giả sử chúng ta có đoạn mã sau và không đầy đủ comments

/** 
* an utterly useless function 
* 
* @param {String} an useless string 
* @param {Boolean} an useless boolean 
* @param {Function} ??? 
*/ 

function Useless (str, bool, callback) { 
    callback(str, bool); 
} 

một cách tốt để nói callback sẽ được gọi với str và bool là các thông số là gì?

Answer 1

Thông thường, bạn sẽ chỉ cần viết một lời kêu cầu của hàm với những cái tên nói:

/* 
* @param {String} input: the text 
* @param {Function} callback(output, hasChanged): called after calculation 
*/ 

Hoặc, nếu các thông số cần giải thích, bạn có thể sử dụng một mô tả multiline:

/* 
* @param {String} input: the text 
* @param {Function} callback(result, change) 
      the function that is called after calculation 
      result {String}: the output of the computation 
      change {Bool}: whether a change has occured 
*/ 

Answer 2

Tôi không biết về bất kỳ quy ước nào về điều này. Tôi sẽ chỉ sử dụng:

@param {Function} Called on success with the response (string) as the first param and the status code (int) as the second 

Tôi biết nó khá dài dòng.

Một lựa chọn khác sẽ làm nó như thế này (tương tự như cách jQuery làm nó, không phải trong mã mà tôi biết, nhưng trong tài liệu của họ)

@param {Function} onSuccess(response, statusCode) 

Dưới đây là một ví dụ http://api.jquery.com/jQuery.ajax/ Đó là khác nhau tất nhiên vì đây là một đối tượng tùy chọn và tài liệu có cấu trúc khác với tài liệu nội tuyến. Nhưng nhìn vào callbacks và bạn sẽ thấy sự giống nhau.

Bạn cũng nên sử dụng gọi lại (response, statusCode) hơn gọi lại (chuỗi, int) để rõ ràng. Nếu bạn phải chọn một cái. Có nghĩa là trước khi nhập.

Answer 3

Vâng, có có nhiều cách để thêm nhận xét trong javascript; Dưới đây là khuyến nghị của tôi /thực tiễn tốt nhất.

sử dụng // tốt hơn /* */ vì sau đó bạn có thể sử dụng sau để lấy ra toàn bộ khối chứa các nhận xét khác. Tuy nhiên, nếu bạn muốn sử dụng công cụ tạo tài liệu tự động, bạn phải sử dụng các nhận xét tương tự như kiểu javaDoc.

Đây là một ví dụ mà sẽ làm việc với YUI DOC (tốt nhất) http://developer.yahoo.com/yui/yuidoc/#start

/** 
* This is a description 
* @namespace My.Namespace 
* @method myMethodName 
* @param {String} str - some string 
* @param {Object} obj - some object 
* @param {requestCallback} callback - The callback that handles the response. 
* @return {bool} some bool 
*/ 
    function SampleFunction (str, obj, callback) { 
     var isTrue = callback(str, obj); // do some process and returns true/false. 
     return isTrue ; 
    } 

params khác Ví dụ: - http://usejsdoc.org/tags-param.html

Hy vọng điều này sẽ giúp bạn :) chức năng