@link causes warning + error when used in namespace with same name as class/interface combo

[frank-weindel]

Search terms

same name interface namespace link

Expected Behavior

No warning or error in the scenario laid out below

Actual Behavior

TypeDoc fails to compile with this warning and error:

warning Failed to resolve {@link AnotherInterface} in SameNameClassNamespace with declaration references. This link will break in v0.24.
error Command failed with exit code 3.

Steps to reproduce the bug

Repro PR:

• For TypeStrong/typedoc#2033 typedoc-repros#19

/**
 * Some code reproducing a bug.
 */
declare namespace SameNameClassNamespace {
  /**
   * This causes an error even though it's relatively correct: {@link AnotherInterface}
   */
  export interface AnInterface {

  }

  /**
   * Some documentation
   */
  export interface AnotherInterface {

  }
}

/*
 * The error goes away in three ways:
 * - Comment out the below class
 * - Comment out the below interface
 * - Even stranger: Make this comment a TSDoc comment (add extra * to beggining of comment),
 *   which will apply to the class.
 *     - This may be a workable workaround
 */


declare class SameNameClassNamespace {

}

/**
 * This interface is used to augment additional keys (from AnInterface) onto SameNameClassNamespace
 */
interface SameNameClassNamespace extends SameNameClassNamespace.AnInterface {

}

export {
  SameNameClassNamespace
};

Environment

• Typedoc version: 0.23.10
• TypeScript version: 4.7.3
• Node.js version: v16.14.0
• OS: macOS 12.2.1

[Gerrit0]

... at this point, surely you're trying to break me, what a convoluted setup XD

Thanks for the minimal repro!

[Gerrit0]

Ah, this makes sense now... confusing bug though.

The link on AnInterface is being resolved as expected. The issue is that the comment is inherited by the class reflection for SameNameClassNamespace. When this happens, the link will then be resolved relative to the class, and TypeDoc today doesn't check for other declaration merged elements when attempting to resolve links

A simpler setup illustrating the same problem is:

namespace Foo {
  export interface Bar {}
}

/** {@link Bar} */
class Foo {}

TypeScript will resolve this link to Foo.Bar... it's not very difficult for TypeDoc to do the same, so I think it's a reasonable change.