Question

我试图用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显示为静态属性，而methodB和methodC（遵循来自here的建议）则根本不显示

如何让JSDoc3使用它们的参数来记录实例方法，而无需重写代码？

Answer 1

您的代码上似乎使用了太多代码。当您使用@constructor时，您不需要@name或@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}）。

Answer 2

@ instance，@ memberOf＆amp;的组合@method应该这样做：

/**
 * This should now be a member function.
 * @instance
 * @memberOf space.someclass
 * @method methodA
 * @param {*} x Some parameter of any type.
 * @return {Object} this.
 */

jsdoc：如何显示实例方法参数？

2 个答案: