Unscoped @link in interface member docs cannot be resolved after inheritance into another package

[yoursunny]

Search terms

@link, interface

Steps to reproduce the bug

https://github.com/TypeStrong/typedoc-repros/pull/43

1. In package lib, interface LibInt has a member whose documentation contains {@link libFunc}, linking to another identifier in the same package.
2. In package wrapping-lib, there's an interface that inherits from LibInt.

Expected Behavior

TypeDoc should be able to resolve @link without NPM scope within the identifiers defined in the same package where the documentation appears.

Actual Behavior

[warning] Failed to resolve link to "libFunc" in comment for @typedoc/wrapping-lib.WrappingInt.bar

This suggests that TypeDoc is attempting to resolve libFunc within the context of wrapping-lib package. Since the @link tag was written in lib package, this identifier should be resolved within that package instead, even if it's inherited.

Environment

• Typedoc version: 0.26.3
• TypeScript version: 5.5.2
• Node.js version: 20.15.0
• OS: Ubuntu 22.04.4

[Gerrit0]

I'm not sure there's a good way to fix this. When TypeDoc is processing wrapping-lib, the comment for bar is just a comment in some declaration file -- there's nothing special about it that says it belongs to another library, and even if we knew it belonged to another library, TypeDoc doesn't have that library in memory at this point, so it can't resolve the comment using the origin library...

[yoursunny]

When TypeDoc is processing wrapping-lib, the comment for bar is just a comment in some declaration file -- there's nothing special about it that says it belongs to another library

Is it possible to track where the .d.ts was generated from?

even if we knew it belonged to another library, TypeDoc doesn't have that library in memory at this point, so it can't resolve the comment using the origin library

Is it possible to read the generated TypeDoc JSON of the origin library, and copy from the documentation of that identifier?

[Gerrit0]

Is it possible to track where the .d.ts was generated from?

Yes, that info is available, unfortunately, it doesn't solve the problem... "in another node_modules folder" doesn't necessarily mean in another library.... what's a "library" can be completely different between projects.

Is it possible to read the generated TypeDoc JSON of the origin library, and copy from the documentation of that identifier?

The problem here is actually that TypeDoc is getting a comment for the member when converting wrapping-lib, and not inheriting it from the parent library's reflection... If TypeDoc didn't add the comment for foo, the comment could be added after merging projects together, which would fix this (might need #2467 too, been a bit since I looked at that code)

The problem with doing this is that TypeDoc doesn't know when converting WrappingInt whether or not Int will be included in the final generated documentation, so can't know whether or not to include a comment. Not including comments for any inherited members would result in significantly worse documentation in the case where the parent class/interface isn't included in the docs, so TypeDoc today errs on the side of always including the comment.

I guess one way to kind of fix this would be to use DeclarationReflection.inheritedFrom and if when restoring the serialized projects the source property on a member of a class/interface indicates that it was inherited from a member we now have, re-replace the comment at that point as the parent's comment will have the correctly resolved link in this case... that.... might work... I'm not sure it's a general solution... it would overwrite any changes which have been made to the child comment by plugins.

[salfagan81]

Search terms

@link, interface

Steps to reproduce the bug

TypeStrong/typedoc-repros#43

1. In package lib, interface LibInt has a member whose documentation contains {@link libFunc}, linking to another identifier in the same package.
2. In package wrapping-lib, there's an interface that inherits from LibInt.

Expected Behavior

TypeDoc should be able to resolve @link without NPM scope within the identifiers defined in the same package where the documentation appears.

Actual Behavior

[warning] Failed to resolve link to "libFunc" in comment for @typedoc/wrapping-lib.WrappingInt.bar

This suggests that TypeDoc is attempting to resolve libFunc within the context of wrapping-lib package. Since the @link tag was written in lib package, this identifier should be resolved within that package instead, even if it's inherited.

Environment

• Typedoc version: 0.26.3
• TypeScript version: 5.5.2
• Node.js version: 20.15.0
• OS: Ubuntu 22.04.4