@link to exported member with declaration reference links to top of module

[aayla-secura]

Search terms

link, declaration references

Expected Behavior

I expect the link to point to the relevant object, class, etc regardless which resolution type is used.

Actual Behavior

When I link to an exported in another module using the declaration reference syntax (because the linked member is not imported by the file for example), the link points to the top/root module and not to the exported member.

Steps to reproduce the bug

For example, moduleA exports someVar, which in the doc has its own page.

If I import this into moduleB and use {@link someVar} it correctly links to it.

If I don't import it and use {@link moduleA!~someVar} it links to moduleA.

Relevant installed packages + versions

[email protected]
[email protected]
[email protected]

tsconfig.json

{
	"compilerOptions": {
		"target": "esnext",
		"module": "preserve",
		"moduleResolution": "node",
		"outDir": "./dist/types/",
		"declaration": true,
		"declarationMap": true,
		"emitDeclarationOnly": true,
		"isolatedModules": true,
		"forceConsistentCasingInFileNames": true,
		"strict": true,
		"noImplicitAny": true,
		"strictNullChecks": true,
		"strictFunctionTypes": true,
		"strictBindCallApply": true,
		"strictPropertyInitialization": true,
		"noImplicitThis": true,
		"useUnknownInCatchVariables": true,
		"alwaysStrict": true,
		"noImplicitReturns": true,
		"noFallthroughCasesInSwitch": true,
		"skipDefaultLibCheck": false,
		"skipLibCheck": false
	},
	"include": ["src/ts/"],
	"typedocOptions": {
		"entryPoints": [
			"src/ts/"
		],
		"entryPointStrategy": "expand",
		"out": "docs/",
		"plugin": ["typedoc-plugin-merge-modules"],
		"mergeModulesMergeMode": "module" // added by plugin typedoc-plugin-merge-modules
	}
}

How you are running TypeDoc + any relevant configuration files

npx typedoc

Environment

• Typedoc version: 0.26.11
• TypeScript version: 5.6.3
• Node.js version: 20.18.0
• OS: Ubuntu on WSL2 on Windows 11

[Gerrit0]

Going to ask for a reproduction that I can easily clone for this one. I don't want to spend time guessing what your setup actually looks at.

Also, please try to reproduce without the plugin. Plugins can do things which will break link resolution.

[aayla-secura]

Apologies, here is a minimal example that shows this: TypeStrong/typedoc-repros#48

The first link in the doc for index.bug that uses declaration references points to /modules/Module.html, while the second one points to /variables/Module.someVar.html. Is my declaration reference syntax incorrect?

[Gerrit0]

That's... interesting. I apparently missed the !~ case when implementing that parser some years ago. According to the tsdoc spec that should be a reference to a local of the module, which isn't something which TypeDoc supports as it only supports exports. TypeDoc should really be emitting an error here.

{@link Module!someVar} works

[Gerrit0]

... or maybe TypeDoc's docs should just be updated to describe how ~ actually works for it. Either way, this declaration reference doesn't parse correctly, so that's a bug.

typedoc/src/lib/converter/comments/declarationReferenceResolver.ts

Lines 275 to 283 in 016e6a1

	// Resolve via "locals"... treat this as a stricter `.` which only supports traversing
	// module/namespace exports since TypeDoc doesn't support documenting locals.
	case "~":
	if (
	refl.kindOf(ReflectionKind.SomeModule | ReflectionKind.Project)
	) {
	high = children?.filter((r) => r.name === path.path) || [];
	}
	break;

[aayla-secura]

Oh, I see where my original mistake was: I was trying to link to a property of an object (which seems to be impossible as they don't have their own anchor or page). And that's why I thought Module!object#prop was not working. Thank you for explaining.

[Gerrit0]

TypeDoc does support one level of properties, though there was a bug prior to the most recent version where the links were resolved incorrectly.