How do deal with @alias and broken @link in <p> tags ?

[Jakobud]

I have a JS Class with various property methods. Some of those methods are alias'es of other methods. I'm trying to figure out how the @alias works with this library.

For example I have this

/**
 * @property removeAll
 * @desc whatever blah blah
 * @returns {this}
 * /
public remove() { ... }

/**
 * @property forgetAll
 * @alias removeAll
 * @returns {this}
 * /
public forgetAll() { return this.removeAll(); }

So removeAll is my class method that does something. forgetAll is just an alias for removeAll and does the exact same thing.

When I run jsdoc2md I get something like this:

• MyClass
  • instance
    • removeAll => this
  • static
    • forgetAll => this

And then later in the doc:

myclass.removeAll() => this

whatever blah blah

Kind: instance method of MyClass
Properties

Name removeAll

forgetAll => this

Kind: global function
Property: forgetAll

So @alias appears to think my alias function is now static and pulls it outside my class as a global function.

How is this all supposed to work exactly?

Also if I try to link to another method like this:

This is an alias method for {@link removeAll}

it just creates markdown like this:

<p>This is an alias method for [removeAll](removeAll)</p>

This does NOT render as a link in the markdown.

Also why doesn't it link to the anchor links that jsdoc2md generates on the page? For example shouldn't it render as this?

[removeAll](#MyClass+removeAll)

?

[75lb]

the @alias and @link tags accept a "namepath".. e.g. @alias module:jsdoc-api~JsdocOptions#pedantic.

To list the available namepaths for your file(s), use --namepaths flag. Then pick the relevant one for your @alias or @link.

$ jsdoc2md index.js --namepaths
{
  "module": [
    "module:jsdoc-api"
  ],
  "class": [
    "module:jsdoc-api~JsdocOptions"
  ],
  "constructor": [],
  "mixin": [],
  "member": [
    "module:jsdoc-api~JsdocOptions#files",
    "module:jsdoc-api~JsdocOptions#source",
    "module:jsdoc-api~JsdocOptions#cache",
    "module:jsdoc-api~JsdocOptions#access",
    "module:jsdoc-api~JsdocOptions#configure",
    "module:jsdoc-api~JsdocOptions#destination",
    "module:jsdoc-api~JsdocOptions#encoding",
    "module:jsdoc-api~JsdocOptions#private",
    "module:jsdoc-api~JsdocOptions#package",
    "module:jsdoc-api~JsdocOptions#pedantic",
    "module:jsdoc-api~JsdocOptions#query",
    "module:jsdoc-api~JsdocOptions#recurse",
    "module:jsdoc-api~JsdocOptions#readme",
    "module:jsdoc-api~JsdocOptions#template",
    "module:jsdoc-api~JsdocOptions#tutorials"
  ],
  "namespace": [],
  "constant": [
    "module:jsdoc-api",
    "module:jsdoc-api~cache"
  ],
  "function": [
    "module:jsdoc-api.explain",
    "module:jsdoc-api.render"
  ],
  "event": [],
  "typedef": [],
  "external": [
    "external:cache-point"
  ]
}

Some example namepath @link tags in this testbed directory. See the JS file there for the source input and MD file for the output.

Does that help?

[Jakobud]

Okay so I tried this. My namepaths are something like this

So I add this:

/**
   * @name set
   * Alias of {@link Cache#put}
   * @memberof Cache
   * @instance
   * @alias Cache#put
   * @example
   * cache.set('foo', 'bar');
   * @returns {this}
   */

And now it spits out this

[75lb]

It seems you're using Typescript (based on seeing public remove() {} in your example code, which is not valid Javascript).. I don't use Typescript so I can't quickly knock up a local test to reproduce your issue.

Could you post a reproduction case? A jsdoc2md command I can run along with the required modules, config and input TS file containing the documented source. Just a minimal example I can quickly run, I don't need your full codebase..

This page states @memberof is not supported. I can't verify that, I'm just skimming the TS docs.

[75lb]

Have you tried using jsdoc directly against your code? If so, does the jsdoc output look correct? jsdoc2md sits downstream of the jsdoc output so it's important to get things looking correct in jsdoc first.

If there's nothing more to add, please feel free to close this.