JSDoc3 & NodeJS link to types from modules

Problem

I try to find how to let JSDoc3 automatically generate links to classes from other modules. I find it hard to explain in words, so let me give some examples. The following script generates the expected output:

/**
 * @constructor
 */
var SomeClass = function(){}

/**
 * @param {SomeClass} someParam description
 */
var someFunc = function(someParam){}

That is, JSDoc3 correctly generates a link from the parameter list of someFunc to the class description of SomeClass. However, when I put SomeClass in an external module I can't seem to let JSDoc3 generate the links:

/**
 * @file SomeClass.js
 * @module SomeClass
 */

/**
 * @constructor
 */
exports.SomeClass(){}


/**
 * @file main.js
 */
var SomeClass = require('./SomeClass');

/**
 * @param {SomeClass} someParam description
 */
function someFunc(someParam){}

Now JSDoc3 correctly generates the documentation for both files, but it doesn't link the parameter type of someFunc to the page of SomeClass. I tried replacing @param {SomeClass} with:

  • @param {SomeClass.SomeClass}
  • @param {SomeClass/SomeClass}
  • @param {@link SomeClass}
  • @param {@link SomeClass.SomeClass}
  • @param {@link SomeClass/SomeClass}

But none of these worked: in all cases the documentation simply shows the text inside the curly brackets (even when I used @link).

How can I let JSDoc3 correctly generate links to the external modules?

Problem courtesy of: Tiddo

Solution

Use the module: prefix when referencing modules. If the module's return value is the class itself, then use module:SomeClass. If it is a property of the module, use module:SomeClass.SomeClass. The @link tag shouldn't be necessary if jsdoc can find a reference to the existing class documentation.

Solution courtesy of: Dan

Discussion

There is currently no discussion for this recipe.

This recipe can be found in it's original form on Stack Over Flow.