Cách tốt nhất để ghi lại các đối tượng và chức năng ẩn danh bằng jsdoc

Question

Chỉnh sửa: Đây là câu hỏi về mặt kỹ thuật gồm 2 phần. Tôi đã chọn câu trả lời hay nhất bao gồm câu hỏi nói chung và được liên kết với câu trả lời xử lý câu hỏi cụ thể.

Cách tốt nhất để ghi lại các đối tượng và chức năng ẩn danh bằng jsdoc là gì?

/** 
* @class {Page} Page Class specification 
*/ 
var Page = function() { 

    /** 
    * Get a page from the server 
    * @param {PageRequest} pageRequest Info on the page you want to request 
    * @param {function} callback Function executed when page is retrieved 
    */ 
    this.getPage = function(pageRequest, callback) { 
    }; 
}; 

Cả đối tượng PageRequest hoặc callback tồn tại trong mã. Chúng sẽ được cung cấp tới getPage() khi chạy. Nhưng tôi muốn có thể xác định đối tượng và chức năng là gì.

tôi có thể nhận được ngay với việc tạo ra các đối tượng PageRequest để ghi nhận rằng:

/** 
* @namespace {PageRequest} Object specification 
* @property {String} pageId ID of the page you want. 
* @property {String} pageName Name of the page you want. 
*/ 
var PageRequest = { 
    pageId : null, 
    pageName : null 
}; 

Và đó là tốt (mặc dù tôi là mở cửa cho những cách tốt hơn để làm điều này).

Cách tốt nhất để ghi lại chức năng callback là gì? Tôi muốn làm cho nó biết trong tài liệu đó, ví dụ, chức năng gọi lại là ở dạng:

callback: function({PageResponse} pageResponse, {PageRequestStatus} pageRequestStatus) 

Bất kỳ ý tưởng làm thế nào để làm điều này?

Answer 1

Bạn có thể ghi lại những thứ mà doesnt tồn tại trong mã bằng cách sử dụng thẻ @name:

 /** Description of the function 
      @name IDontReallyExist 
      @function 
      @param {String} someParameter Description 
     */ 


     /** The CallAgain method calls the provided function twice 
      @param {IDontReallyExist} func The function to call twice 
     */ 
     exports.CallAgain = function(func) { func(); func(); } 

Đây là @name tag documentation. Bạn có thể tìm thấy name paths cũng hữu ích.

Answer 2

Bạn có thể sử dụng @see để liên kết với phương thức khác trong cùng một lớp. Phương pháp này sẽ không bao giờ được sử dụng, nó sẽ chỉ ở đó vì mục đích tài liệu.

/** 
* @class {Page} Page Class specification 
*/ 
var Page = function() { 

    /** 
    * Get a page from the server 
    * @param {PageRequest} pageRequest Info on the page you want to request 
    * @param {function} callback Function executed when page is retrieved 
    * @see #getPageCallback 
    */ 
    this.getPage = function (pageRequest, callback) { 
    }; 

    /** 
    * Called when page request completes 
    * @param {PageResponse} pageResponse The requested page 
    * @param {PageRequestStatus} pageRequestStatus Status of the page 
    */ 
    //#ifdef 0 
    this.getPageCallback = function (pageResponse, pageRequestStatus) { }; 
    //#endif 
}; 

Nếu bạn đang sử dụng một số loại hệ thống xây dựng, phương pháp giả có thể dễ dàng bị bỏ qua khỏi bản dựng.

Answer 3

@link có thể thêm liên kết nội tuyến vào các phương pháp và lớp học.

/** 
* Get a page from the server 
* @param {PageRequest} pageRequest Info on the page you want to request 
* @param {function} callback Function executed when page is retrieved<br /> 
* function({@link PageResponse} pageResponse,{@link PageRequestStatus} pageRequestStatus) 
*/ 
this.getPage = function (pageRequest, callback) { 
}; 

Không lý tưởng, nhưng thực hiện công việc.

Answer 4

Chú thích trình biên dịch đóng cửa của Google có Type Expressions cho điều này bao gồm khả năng chỉ định loại cho các đối số cụ thể, kiểu trả về và thậm chí điều này. Nhiều thư viện đang xem xét theo chú thích của Trình biên dịch đóng cửa của Google, vì chúng muốn sử dụng nó để thu hẹp mã của chúng. Vì vậy, nó có một số động lực. Nhược điểm là tôi không thấy một cách để đưa ra mô tả.

Để cung cấp mô tả có lẽ cách tiếp cận Công cụ JSDoc Parameters With Properties sẽ hoạt động (xem ở cuối trang). Đó là những gì tôi đang làm ngay bây giờ. Bộ công cụ JSDoc đang bắt đầu làm việc trên V3, vì vậy phản hồi có thể tốt.

Answer 5

Để khen câu trả lời của thợ mộc, tôi đã cung cấp ví dụ cho thấy những gì JsDoc with Google Closure Compiler cho phép bạn làm.

Lưu ý rằng các loại ẩn danh được loại bỏ khỏi tệp được rút gọn đã tạo và trình biên dịch đảm bảo các đối tượng hợp lệ được chuyển vào (nếu có thể).Tuy nhiên, ngay cả khi bạn không sử dụng trình biên dịch, nó có thể giúp các nhà phát triển và các công cụ tiếp theo như WebStorm (IntelliJ) hiểu nó và cung cấp cho bạn mã hoàn thành.

// This defines an named type that you don't need much besides its name in the code 
// Look at the definition of Page#getPage which illustrates defining a type inline 
/** @typedef { pageId : string, pageName : string, contents: string} */ 
var PageResponse; 

/** 
* @class {Page} Page Class specification 
*/ 
var Page = function() {  
    /** 
    * Get a page from the server 
    * @param {PageRequest} pageRequest Info on the page you want to request 
    * 
    * The type for the second parameter for the function below is defined inline 
    * 
    * @param {function(PageResponse, {statusCode: number, statusMsg: string})} callback 
    *  Function executed when page is retrieved 
    */ 
    this.getPage = function(pageRequest, callback) { 
    }; 
}; 

Answer 6

Bạn có thể sử dụng @callback hoặc @typedef.

/** 
* @callback arrayCallback 
* @param {object} element - Value of array element 
* @param {number} index - Index of array element 
* @param {Array} array - Array itself 
*/ 

/** 
* @param {arrayCallback} callback - function applied against elements 
* @return {Array} with elements transformed by callback 
*/ 
Array.prototype.map = function(callback) { ... }