node.js - 不同文件中定义的对象的 JSdoc

Question

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

A.js

function put(persons) {
}

entities.js

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

现在，在 A.js 中，当我为方法 put 编写 JSdoc 时，我应该为 persons 输入什么类型？理想情况下应该是 {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 .

In most cases, your CommonJS or Node.js module should include a standalone JSDoc comment that contains a @module tag. The @module tag's value should be the module identifier that's passed to the require() function. For example, if users load the module by calling require('my/shirt'), your JSDoc comment would contain the tag @module my/shirt.

If you use the @module tag without a value, JSDoc will try to guess the correct module identifier based on the filepath.

When you use a JSDoc namepath to refer to a module from another JSDoc comment, you must add the prefix module:. For example, if you want the documentation for the module my/pants to link to the module my/shirt, you could use the @see tag to document my/pants as follows:

这是另一个使用您的确切文件和附加 @module 声明的示例:

实体.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
};

精确文件示例渲染