@link not resolving across packages

[KDean-Dolphin]

Search terms

link url package resolve

Expected Behavior

This is typedoc.json for my documentation project:

{
  "$schema": "https://typedoc.org/schema.json",
  "plugin": [
    "typedoc-github-theme"
  ],
  "entryPoints": [
    "../core",
    "../utility",
    "../gs1"
  ],
  "entryPointStrategy": "packages",
  "includeVersion": true,
  "out": "api",
  "theme": "typedoc-github-theme",
  "sourceLinkExternal": true
}

Every package has a similar typedoc.json; this is the one for the "gs1" package:

{
  "$schema": "https://typedoc.org/schema.json",
  "sourceLinkExternal": true,
  "groupOrder": [
    "Enumerations",
    "Type Aliases",
    "Interfaces",
    "Classes",
    "Variables",
    "Enumeration Members",
    "Properties",
    "Constructors",
    "Accessors",
    "Methods",
    "*"
  ],
  "sort": [],
  "name": "GS1",
  "entryPoints": [
    "src/index.ts"
  ]
}

This is from variable documentation in the "gs1" package in my code:

/**
 * GS1 AI encodable character set 82 creator. Supports {@linkcode Exclusion.AllNumeric}.
 */

Exclusion is an enumeration in the "utility" package, of which AllNumeric is a member.

What I expect to see in the HTML is this:

<p>GS1 AI encodable character set 82 creator. Supports <a href="../enums/Utility.Exclusion.html#AllNumeric" class="tsd-kind-enum-member"><code>Exclusion.AllNumeric</code></a>.</p>

Actual Behavior

What I'm getting instead is no link at all:

<p>GS1 AI encodable character set 82 creator. Supports Exclusion.AllNumeric.</p>

Steps to reproduce the bug

As above. If I change the link target to something unresolvable, I get a warning message in the console:

[warning] Failed to resolve link to "ExclusionX.AllNumeric" in comment for GS1.AI82_CREATOR

It seems that TypeDoc is resolving the link, but not rendering it.

Environment

• TypeDoc version: 0.26.5
• TypeScript version: 5.5.4
• Node.js version: 21.7.3
• OS: macOS Sonoma 14.6.1

[Gerrit0]

https://github.com/Gerrit0/typedoc-packages-example/compare/typedoc-gh2681 seems to work... without a reproduction, I can't possibly fix this. The fix for #2680 might possibly have fixed this... impossible to say.

[KDean-Dolphin]

Not fixed. I'll see what I can do about setting up a reproducible case for this and for #2680.

[KDean-Dolphin]

Here you go.

https://github.com/KDean-Dolphin/TypeDoc

[Gerrit0]

So there's a couple things here...

TypeDoc should be reporting a broken @link here. (also for @link Generator) because it is not fully resolved. The link is rendering as expected, but should be producing warnings.

The link is not resolved because TypeDoc is resolving imports for unrelated projects via file paths and when converting utility TypeDoc finds that Exclusion is created/owned by ../utility/src/character_set.ts. When converting gs1, TypeDoc finds that Exclusion is owned by ../utility/src/index.ts because tsup generates a bundled declaration file rather than referencing the associated ts file.

There are a few ways to fix this.

1. Build utility with rm -r dist && npx tsc --outDir dist --declaration --declarationMap before generating docs.

   The existence of the declaration map + non-bundled declaration files allows TypeDoc to figure out that the Exclusion referenced by the gs1 project is actually the one declared in utility.

2. Import from the src directory, not the dist directory.

   diff --git a/gs1/src/check.ts b/gs1/src/check.ts
   index 6f6e2a1..0a32aa3 100644
   --- a/gs1/src/check.ts
   +++ b/gs1/src/check.ts
   @@ -1,4 +1,4 @@
   -import { Exclusion } from "../../utility/dist/index.js";
   +import { Exclusion } from "../../utility/src/index.js";
    
    /**
     * Do something with an {@link Exclusion} parameter.

   This appears to be supported by tsup and is supported by TypeScript/TypeDoc. You can even take this a step further and set up project references so TypeScript knows how to more intelligently create projects (generally resulting in better intellisense performance, depending on the project size, sometimes significantly better)

   This also has the benefit of no longer having to build the utility project to make intellisense work in the gs1 project.

[KDean-Dolphin]

I'll look into that and let you know.

The repository I gave you was vastly simplified. In reality, the utility package appears in the gs1 package.json as a dependency, with "npm link" used to bridge the directories. In that architecture, my import looks like this:

import { Exclusion } from "@myorg/utility";

I replaced it with a reference to the dist/index.js file because I specifically didn't want TypeDoc looking at the source, because it can't see the source in the real implementation.

[KDean-Dolphin]

One more thought...

The reason I expected it to work was because I was explicitly declaring, in my core doc project, the projects in order of dependency. In other words, I was expecting TypeDoc to use what is in utility to resolve some of what is in gs1.

[Gerrit0]

I specifically didn't want TypeDoc looking at the source, because it can't see the source in the real implementation.

But when generating docs for utility, TypeDoc is told to look at that source! That's what's causing the disconnect here. TypeDoc doesn't just match on symbol names as they aren't necessarily (or even likely!) globally unique. It also considers the file name that symbols originate in.

If you generated docs for the utility module with the tsup generated declaration file, then the links would have worked as you expected. (Even if you had generated gs1 first, TypeDoc stores a ReflectionSymbolId for elements not in the documentation which is effectively file path + name, and the projects are merged together after all have been created, so the order doesn't matter)