JSdoc用于在不同文件

Question

我在文件A.js中有函数，它接受一个say的数组，Person在其他文件中定义，entities.js。

A.js

function put(persons) {
}

entities.js

function Person(name) {
   this.name = name;
   this.age = 10;
}

现在，在A.js中，当我为方法put编写JSdoc时，我应该为人员输入什么类型？理想情况下应该是{Person []}，但我不知道应该如何引用，因为它存在于不同的文件中。有一种方法我可以要求entities.js文件： -

var Person = require('./entities').Person;

然后如果我做{Person []}，它可以工作，但我只是想为JSDoc导入定义？这是唯一的办法吗？

Answer 1

你会认为这看起来很可怕，但你可以这样做@param {module:someModule/SubModule~ExportedClass}：

MyType.js

/**
 * A dummy type module
 * @module myModule/MyType
 */

/**
 * Dummy type
 */
class MyType {
    /**
     * Creates a MyType
     * @param {Number} foo Some var
     * @param {Number} bar Some other var
     */
    constructor(foo, bar) {
        this.foo = foo;
        this.bar = bar;
    }
}

module.exports = MyType;

使用MyType

的一些代码

/**
 * Test
 * @inner
 * @param {module:myModule/MyType~MyType} c The caption
 */
function test(c){
    console.log(c);
}

这会给你这样的东西：

需要注意的关键是你需要对JSDoc真正明确。该文档提供了一个说明，详细说明了如何使用module:MODULE_NAME语法在CommonJS Modules: Module identifiers中指定某些对象或导出是模块的一部分。

  

在大多数情况下，您的CommonJS或Node.js模块应包含一个   包含@module tag的独立JSDoc注释。 @module代码的值   应该是传递给require()的模块标识符   功能。例如，如果用户通过调用加载模块   require('my/shirt')，您的JSDoc注释将包含标记   @module my/shirt。

     

如果你使用没有值的@module标签，JSDoc会尝试猜测   基于文件路径的正确模块标识符。

     

使用JSDoc时   namepath指的是   来自另一个JSDoc注释的模块，您必须添加前缀module:。   例如，如果您需要模块my/pants的文档   要链接到模块my/shirt，您可以使用@see tag将my/pants记录为   如下：

以下是使用您的确切文件以及其他@module声明的另一个示例：

entities.js

/**
 * Person Module
 * @module Person
 */

/**
 * Creates a person
 * @class
 */
function Person(name) {
    this.name = name;
    this.age = 10;
}

module.exports = {
    Person: Person
};

A.js

var Person = require("./entities").Person;

/**
 * Module for putting people somewhere
 * @module A
 */

/**
 * Does something with persons
 * @param {module:Person~Person[]} persons Some people
 */
function put(persons) {}

module.exports = {
    put: put
};

精确文件示例渲染