JSDoc3 does not generate hyperlinks to namespaces in NodeJS

Question

I bet this is a stupid question but I somehow can't find the reason for this in any document I have found since this morning.

I am experienced in using JavaDoc but somehow even though the syntax of @link is the same, JSDoc3 simply does not generate hrefs to the related elements. I have tried out every possible way for the namespaces to link (also obviously wrong ones), but non of them changes the result a bit. I expected to receive a link by writing {@link #myFunction} or at least {@link MyClass#myFunction}, but neither of this created a hyperlink. Here is the code I have tested this with:

/**
 * See {@link myOtherFunction} and [MyClass's foo property]{@link MyClass#foo}.
 * Or look at {@link https://github.com GitHub}
 */
function myFunction(){};

/**
 * See {@link #myFunction} or maybe {@link #myFunction()}
 */
function myOtherFunction() {};

I am generating it with ./node_modules/.bin/jsdoc ./* --configure ./conf.json and my default config file is:

{
    "tags": {
        "allowUnknownTags": true
    },
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": [],
    "templates": {
        "cleverLinks": true,
        "monospaceLinks": false,
        "default": {
            "outputSourceFiles": true
        }
    }
}

(it makes no difference if I write "cleverLinks": false,)

This is how my output looks like:

So as one can see the URL is generated properly but the namespaces are not.

I am just badly confused since I can nowhere find a description that something must be done in order to generate hrefs to my namespaces. Additionally jsdoc says:

The {@link} inline tag creates a link to the namepath or URL that you specify. When you use the {@link} tag, you can also provide link text, using one of several different formats. If you don't provide any link text, JSDoc uses the namepath or URL as the link text.

which does not sound like there needs to be done anything in order to generate links to the namepaths.

And it also defines the syntax to be:

{@link namepathOrURL}
[link text]{@link namepathOrURL}
{@link namepathOrURL|link text}
{@link namepathOrURL link text (after the first space)}

My namepaths are okay as well since webstorm is able to resolve them directly.

What am I missing so badly?

Best regards, Vegaaaa

Answer 1

I have found out my issue was related to the usage of JSDoc with CommonJS (NodeJS). After several hours of googling and trial and error I have managed to end up with how it working differently in NodeJS. I might play around with @inner and @instance but this resolves the question why JSDoc did not want to generate links for my NodeJS Code.

It is due to the fact that CommonJS's scope works differently to client side JS, which has one reason in the definition of NodeJS modules. Thus one need to tell JSDoc how to resolve a variable by adding the @module tag for a module and referencing to members of a module by resolving its relationship like {@link module:MODULE_NAME~instanceName}.

Here is an example with the corresponding generated html. Hope this helps someone running in the same issues like me.

Best regards,

Vegaaaa

/**
 * @module lib
 */

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

};

/**
 * Some doc...
 */
var moduleFunction = function () {

  /**
   * @type {number}
   */
  var innerVar = 0;

  /**
   * @type {number}
   */
  this.instanceVar = 0;

  /**
   * @memberOf module:lib~moduleFunction
   */
  function staticVar() {
    console.log(0)
  }
}

/**
 * Link to this module (identified by @module lib in the beginning): {@link module:lib} <br/>
 * Link to my constructor: {@link module:lib~SomeClass} <br/>
 * Link to a module function: {@link module:lib~moduleFunction} <br/>
 * Link to an instance variable of a module function: {@link module:lib~moduleFunction#instanceVar} <br/>
 * Link to a inner variable within a module function: {@link module:lib~moduleFunction~innerVar} <br/>
 * Link to a static variable within a module function: {@link module:lib~moduleFunction.staticVar} <br/>
 */
function documentedFunction(){}

---