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 与 export.xxxx
• 声明内部类 @private，声明所有内容 @private，但导出除外
• 将 @module 声明移动到第一次导出之前（然后一团糟，有些东西被提升为“全局”，即使它在主闭包内！！）
• 如果我在导出声明之前添加@exports <modulename>，则方法会记录在案（与类方法混合）

我已经尝试了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

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

关键似乎是在 @constructor 之前使用 @exports <modulename>.<classname> ，这样该类出现在“类”下的索引中，并且其方法正确记录如果方法声明为 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
     }
})()