用jsdoc記錄匿名對象和函數的最佳方法

Question

編輯：這在技術上是一個2部分問題。我已經選擇了覆蓋此問題的一般答案，並與處理具體問題的答案相關聯。

用jsdoc記錄匿名對象和函數的最佳方式是什麼？

/** 
* @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) { 
    }; 
}; 

無論是PageRequest對象或callback中代碼存在。它們將在運行時提供給getPage()。但我想能夠定義對象和功能是什麼。

我可以逃脫創建PageRequest對象文件證明：

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

這很好（雖然我接受更好的方法來做到這一點）。

記錄callback函數的最佳方式是什麼？我想讓它知道，例如，回調函數是在格式的文檔中：

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

任何想法如何做到這一點？

Answer 1

您可以通過使用@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(); } 

這裏是@name tag documentation。你也許會發現name paths也很有用。

Answer 2

您可以使用@see鏈接到同一個類中的另一個方法。該方法永遠不會被使用，它只是爲了文檔的目的。

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

如果您正在使用某種形式的編譯系統，虛擬方法可以很容易地從構建省略。

Answer 3

@link可以添加到方法和類的內聯鏈接。

/** 
* 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) { 
}; 

不理想，但它完成了工作。

Answer 4

爲此，Google Closure編譯器註釋具有Type Expressions，其中包括爲特定參數，返回類型甚至是此類指示類型的能力。許多圖書館都在關注Google Closure Compiler Annotations，因爲他們想用它來縮小他們的代碼。所以它有一些動力。缺點是我沒有看到描述的方式。

爲了提供描述，可能JSDoc Toolkit Parameters With Properties的方法將工作（看看頁面的底部）。這就是我現在正在做的事情。 JSDoc Toolkit正在準備開始使用V3，所以反饋可能會很好。

Answer 5

爲了恭維studgeek的回答，我提供了一個示例，顯示JsDoc with Google Closure Compiler可以讓你做什麼。

請注意，記錄的匿名類型將從生成的縮小文件中移除，並且編譯器確保傳入有效對象（如果可能）。但是，即使您不使用編譯器，它也可以幫助下一個開發人員和工具（如WebStorm（IntelliJ））理解它併爲您提供代碼完成。

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

您可以使用@callback或@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) { ... }