使用 jsdoc 记录匿名对象和函数的最佳方法

Question

编辑：从技术上讲，这是一个由两部分组成的问题。我选择了涵盖一般问题的最佳答案，并链接到处理特定问题的答案。

使用 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: 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 标签文档。您可能会发现名称路径也很有用。

Answer 2

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

Answer 3

为了补充 studgeek 的回答，我提供了一个示例，展示了带有 Google Closure 的 JsDoc编译器可以让你做到。

请注意，记录的匿名类型将从生成的缩小文件中删除，并且编译器确保传入有效对象（如果可能）。但是，即使您不使用编译器，它也可以帮助下一个开发人员和 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 4

希望我在这个话题上还不算太晚，但是你可以做这样的事情，

/**
  * Get a page from the server
  * @param {PageRequest} pageRequest
  * @param {(pageResponse: PageResponse, pageRequestStatus: PageRequestStatus) => void} callback
  */
this.getPage = function(pageRequest, callback) {}

这种方法的缺点是你无法记录每个参数的作用。

Answer 5

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

Google Closure 编译器注释具有类型表达式，用于这包括指示特定参数的类型、返回类型甚至 this 的能力。许多库正在考虑遵循 Google Closure Compiler Annotations，因为他们想用它来缩小代码。所以它有一些动力。缺点是我看不到给出描述的方法。

为了提供描述，JSDoc Toolkit Parameters With Properties 方法可能会起作用（查看页面底部）。这就是我现在正在做的事情。 JSDoc Toolkit 正准备在 V3 上开始工作，因此反馈可能会很好。

Answer 7

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

如果您使用某种构建系统，则可以轻松地从构建中省略虚拟方法。