1

我正在尝试使用 JSDoc3 记录一些旧代码，并且我一直试图让它在文档中包含实例方法的参数 - 或者根本将任何东西显示为实例属性。我怀疑问题是代码不遵循在 javascript 中伪造类的预期习语，但我想在开始重写任何内容之前记录所有内容。我试图用实际代码的结构来做一个问题的小例子：

/**
 * Global function
 * @param  {Object} v Stuff that they're trying to avoid making global
 * @return {Object}   Updated v
 */
jsdoc_test = function( v ) {
    /**
     * Some stuff is defined in this namespace
     * @namespace space
     */
    var space = {};
    /**
     * Something that acts like a class
     * @name space.someclass
     * @memberOf space
     * @constructor
     * @type {function}
     * @param  {any}    y blah blah
     * @return {Object}   The constructed object
     */
    space.someclass = function( w ) {
        var obj = {
            source:  w,        // might need this again
            derived: foo( w ), // what we usually need
            etc:     "etc"     // and so on
        };
        /**
         * This should be a member function, but it appears as a static property
         * @name space.someclass.methodA
         * @memberOf space.someclass
         * @type {function}
         * @instance
         * @param  {any}    x Parameters do not appear in documentation
         * @return {Object}   this
         */
        obj.methodA = function( x ) {
            bar( x ); // or whatever methodA does
            return this;
        }
        /**
         * This should be a member function, but it doesn't show up at all
         * @name space.someclass.methodB
         * @memberOf space.someclass#
         * @type {function}
         * @param  {any}    y Parameters do not appear in documentation
         * @return {Object}   this
         */
        obj.methodB = function( y ) {
            baz( y ); // or whatever methodB does
            return this;
        }
        return obj;
        /**
         * This should be a member function, but it doesn't show up at all
         * @name space.someclass.methodC
         * @memberOf space.someclass.prototype
         * @type {function}
         * @param  {any}    z Parameters do not appear in documentation
         * @return {Object}   this
         */
        obj.methodC = function( z ) {
            qux( z ); // or whatever methodC does
            return this;
        }
        return obj;
    }
    // ...
}

我希望所有三种方法都作为实例方法出现在生成的文档中。实际上，methodA显示为静态属性，而methodBand methodC（遵循此处的建议）根本不出现

如何让 JSDoc3 记录实例方法及其参数，而无需重写代码？

4

2 回答 2

2

@instance、@memberOf 和 @method 的组合应该可以做到：

/**
 * This should now be a member function.
 * @instance
 * @memberOf space.someclass
 * @method methodA
 * @param {*} x Some parameter of any type.
 * @return {Object} this.
 */
于 2016-08-02T10:20:21.040 回答
0

看起来您在代码上使用了太多标签。当您使用 时@constructor，您不需要@nameor @type，因为使用构造函数涵盖了这些内容。

所以，我认为你有两个选择。

使用@constructor和删除冗余（冲突）标签：

/**
 * Something that acts like a class
 * @constructor space.someclass
 * @memberOf space
 * @param  {any}    y blah blah
 * @return {Object}   The constructed object
 */

或者，如果您不想使用@constructor标签，请自己添加适当的提示：

/**
 * Something that acts like a class
 * @name space.someclass
 * @memberOf space
 * @kind class
 * @param  {any}    y blah blah
 * @return {Object}   The constructed object
 */

在这两种情况下，@type都是多余的，因为您正在记录一个类；从技术上讲，该类型将是您的函数的全名（即@type {space.someclass}）。

于 2015-05-06T14:12:18.387 回答