JSdoc for objects defined in different file

Question

I have function in file A.js which accepts an array of say, Person which is defined in other file, entities.js.

A.js

function put(persons) {
}

entities.js

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

Now, in A.js, when I am writing JSdoc for method put, what should I put in type for persons? It should be ideally be {Person[]} but I don't know how should I reference since that exists in different file. There is one way I could require entities.js file like :-

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

and then if I do {Person[]}, it works but I just want to import the definition just for JSDoc? Is this the only way to do?

Answer 1

You're going to think this looks hideous, but you can do this @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;

Some code that uses MyType

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

This would give you something like this:

---

The key thing to note is that you need to be really explicit with JSDoc. The documentation provides a note detailing how to specify that certain objects or exports are part of a module using the module:MODULE_NAME syntax here: 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:

Here is another example using your exact files with the additional @module declarations:

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
};

Exact File Example Render