jsdoc没有正确记录nodejs模块

Question

我正在尝试让JSDOC(3)正确记录我的NodeJS模块.虽然简单的模块工作,但我找不到记录稍微复杂的模块的方法.

我的NodeJS模块具有以下结构:

/** @module MyModule */
(function() {


     function functionToExportOne {...}

     function functionToExportTwo {...}

     /** 
      * @module MyModule.ClassToExportOne
      * @constructor 
      */
     function ClassToExportOne {

           this.classMethodOne=function() { ... }
           this.classMethodTwo=function() { ... }

     }

     /** @constructor */
     function ClassToExportTwo {

           function classMethodOne() { ... }
           function classMethodTwo() { ... }

           return /** @lends {ClassToExportTwo.prototype} */ {

               methodOne:classMethodOne,
               methodTwo:classMethodTwo
           }
     }
     /** @exports MyModule */  <--- late addition, see comments
     module.exports={
         functionOne:functionToExportOne,
         functionTwo:functionToExportTwo,
         classOne:ClassToExportOne,
         classTwo:ClassToExportTwo
     }
})()

好吧,如您所见,模块导出方法和类构造函数.没什么好奇怪的.

问题是,JSDOC

• 总是无法识别内部类,
• 将第一个内部类方法误认为(外部)模块的方法,
• 总是跳过真正导出的模块方法.
• 我最接近的是,ClassToExportOne当我使用@module MyModule.<className>后跟@constructor(按此顺序):在这种情况下,类被识别,但只记录构造函数,并且其方法被记录为属于父模块

我已经尝试了数千种不同的组合而没有成功:

• 使用this.method=function() {...}(如图所示ClassToExportOne)定义内部类方法或使用方法返回对象@lends {ClassToExportTwo.prototype}(如图所示ClassToExportTwo)
• @module MyModule.ClassToExportOne在每个类的标题中使用
• 定义module.exports vs exports.xxxx
• 宣布内部阶级@private,宣布@private除出口之外的一切
• 将@module声明移到第一次出口之前(总是一团糟,一些东西被提升为"全局",即使它在主要封闭内!)
• 如果我@exports <modulename>在export声明之前添加,则记录这些方法(与类方法混合)

我已经尝试了http://usejsdoc.org/howto-commonjs-modules.html中建议的所有内容,但没有成功.

我确定我错过了什么,却找不到什么.

Answer 1

以下内容适用于jsdoc 3.3.3：

/**
 * Example model.
 *
 * @module model/example
 */
module.exports = (function () {
    /**
     * Constructor function.
     *
     * @exports model/example.Example
     * @constructor
     * @param {string} id
     */
    var example = function Example(id) {
        this.id = id;
    };

    /**
     * Returns the ID.
     *
     * @memberof model/example.Example
     * @returns {string} the id
     */
    example.prototype.getId = function () {
        return this.id;
    };

    return example;
}());

和创建模型实例的示例：

var example = new Example("ID");
console.log(example.getId());

Answer 2

我讨厌回答我自己的问题，但经过更多的尝试和错误，我得到了相当满意的结果。如果这是正确的方法，请随时发表评论，但事实是文档现在已正确生成:)

关键似乎是使用@exports <modulename>.<classname>before @constructor，这样类就出现在“classes”下的索引中，并且其方法被正确记录，如果方法是用 this.method=function() {...}

如果可能的话，我仍然想找到一种方法来完成这项工作，对于 ClassToExportTwo 中描述的情况，有时定义这样的类对我来说非常方便，特别是对于调用私有方法的长类，这样我就可以避免完全在类中使用“this”（优化）。

这是适合我的模板：

/** @module MyModule */
(function() {


     function functionToExportOne {...}

     function functionToExportTwo {...}

     /** works !!
      * @exports MyModule.ClassToExportOne
      * @constructor 
      */
     function ClassToExportOne {

           function innerMethod() { ... }

           // this works: assigning methods to this

           this.classMethodOne=function() { ... }
           this.classMethodTwo=function() { ... }

     }

     /** does not work
      * @exports MyModule.ClassToExportTwo
      * @constructor 
      */         
     function ClassToExportTwo {

           function classMethodOne() { ... }
           function classMethodTwo() { ... }

           // this DOES NOT WORK !! Methods get mixed with parent module
           return  {

               methodOne:classMethodOne,
               methodTwo:classMethodTwo
           }
     }

     // no more @exports here as it duplicates definitions in the docs
     module.exports={
         /** blah blah function description */
         functionOne:functionToExportOne,
         /** blah blah function description */
         functionTwo:functionToExportTwo,
         /** blah blah function description */
         classOne:ClassToExportOne,
         /** blah blah function description */
         classTwo:ClassToExportTwo
     }
})()