如何使用 jsdoc 记录 knockout.js 视图模型？答案

【问题标题】：How can I document a knockout.js view model with jsdoc?如何使用 jsdoc 记录 knockout.js 视图模型？
【发布时间】：2014-04-06 20:22:09
【问题描述】：

我已经尝试使用命名空间和@memberOf 标签，但在生成的 API 文档中我仍然没有任何类成员或方法。

下面是一些示例代码：

/**
 * Test file
 * @namespace test
 */

/**
 * my view model
 * @class MyViewModel
 * @memberOf test
 */
function MyViewModel() {
    var self = this;

    /**
     * test observable
     * @type {Object}
     * @memberOf test.MyViewModel#
     */
    self.testObservable = ko.observable();

    /**
     * test function
     * @memberOf test.MyViewModel#
     */
    self.testObservable = function() {
        // do something
    };
}

【问题讨论】：

标签： javascript knockout.js jsdoc

【解决方案1】：

如果您使用@memberof!，您的@memberof 标签将起作用。感叹号强制 jsdoc 遵循您提供的内容。如果你不使用感叹号，jsdoc 会判断它比你更清楚，并忽略该标签。但是使用@memberof! 仍然让它看起来很时髦。您可以做的是删除@memberof 标签并使用@lends，如下所示：

/**
 * Test file
 * @namespace test
 */

/**
 * my view model
 * @class MyViewModel
 * @memberOf test
 */
function MyViewModel() {
    /** @lends test.MyViewModel# */
    var self = this;

    /**
     * test observable
     * @type {Object}
     */
    self.testObservable = ko.observable();

    /**
     * test function
     */
    self.testObservable = function() {
        // do something
    };
}

【讨论】：

【解决方案2】：

当您将变量附加到self 时，jsdoc 似乎很混乱。 JSDoc 实际上会解析您的代码以查找变量的名称，这似乎无法处理您在类上定义属性的方式。（虽然这是一种很常见的定义方式）。

我通过 jsdoc 运行了这段代码，它记录得很好：

/**
 * Test file
 * @namespace test
 */

/**
 * my view model
 * @class MyViewModel
 * @memberOf test
 */
function MyViewModel() {
    var self = this;

    /**
     * test observable
     * @type {Object}
     * @memberOf test.MyViewModel#
     */
    var testObservable = ko.observable();
}

你可以这样工作：

/**
 * Test file
 * @namespace test
 */

/**
 * my view model
 * @class MyViewModel
 * @memberOf test
 */
function MyViewModel() {
    var self = this;

    /**
     * test observable
     * @type {Object}
     * @memberOf test.MyViewModel#
     */
    var testObservable = self.testObservable = ko.observable();
}

不过，这似乎是一种非常烦人的方式:(

我的建议

使用 yuidoc 根本不解析您的 javascript，而是取决于您明确描述每个属性。以下是我将如何使用 yuidoc 记录您的代码：

/**
 * Test file
 * @namespace test
 */

/**
 * my view model
 * @class MyViewModel
 * @memberOf test
 */
function MyViewModel() {
    var self = this;

    /**
     * test observable
     * @property testObservable
     * @type {Object}
     */
    self.testObservable = ko.observable();

    /**
     * test function
     * @property testObservable
     */
    self.testObservable = function() {
        // do something
    };
}

【讨论】：