using {@link} to reference local monorepo package type with Declaration Reference

[jviall]

Howdy! This is a really sweet project, thanks to all you maintainers :)

I have a monorepo (i.e. entryPointStrategy: packages) where some packages import types from others. When I reference symbols of other packages that are imported, TypeDoc resolves the reference perfectly well:

import type { Foo } from "@org/package/folder/module.ts"

const bar: Foo = {};

/**
 * {@link Foo } this works fine
 */
function yay() {
}

However, when the given symbol is not imported, I cannot at all seem to figure out how to properly spell out the declaration reference:

// the Foo symbol isn't imported but I want to link to it

/**
 * {@link module!Foo } this doesn't work
 */
function bummer() {
}
/**
 * {@link @org/package/folder/module!Foo } doesn't work either
 */
function sad() {
}
/**
 * {@link org_package.folder_module!Foo } nope :/
 */
function tragic() {
}
/**
 * {@link "packageFolder/src/module.ts"!Foo } ૮╥﹏╥ა
 */
function hopeless() {
}

Mind you all of these imports are for local packages that are part of my monorepo--not 3rd party packages in node_modules (though I'm also curious how I would reference exports from those when not in the document scope as well!).

In case it's relevant, Typescript is resolving all of my monorepo imports using the Node resolutions I've defined in each package.json:

{
  "name": "@org/package",
  "imports": {
    "#*": "./src/*"
  },
  "exports": {
    "./package.json": "./package.json",
    "./*": {
      "types": "./src/*",
      "default": "./src/*"
    }
  }
}

I would share my code but it's a private repo!

[Gerrit0]

When you render the docs to HTML, TypeDoc includes breadcumbs at the top of each page which can be used to easily determine a declaration reference which will work, for example:

https://gerritbirkeland.com/typedoc-packages-example/interfaces/_typedoc_lib.LibInt.html

Has:

Packages Example / @typedoc/lib / LibInt

The "Packages Example" is the name provided to typedoc for the entire docs, and isn't included in the declaration reference, so the reference is: @typedoc/lib!LibInt

If LibInt was inside a namespace Lib which was documented by TypeDoc, it'd instead be @typedoc/lib!Lib.LibInt, the important thing is that the declaration reference has to match the model structure which TypeDoc renders, which isn't necessarily the same as the file structure.

Given your example links, what will probably work is {@link @org/package!Foo}

[jviall]

@Gerrit0 Ok i've created a stackblitz to reproduce what I'm experiencing, following my example above: https://stackblitz.com/edit/stackblitz-starters-iqnxyspj?file=bar%2Fsrc%2Ffolder%2FbarFolderModule.ts

The above repro has the following structure:

It's the reference to @org/foo!foo in @org/bar/src/folder/barFolderModule.ts that doesn't work as expected.
That same file also makes a reference to the nearly identically structured org/baz!IBaz, but this one works--the only difference is that the @org/foo project has a @org/foo/src/fooModule.ts file, which I assume changes the resulting reference path that TypeDoc generates for @org/foo.folder/fooFolderModule.foo? But it seems like this may be a bug because I can't manage to get any good reference to foo() without importing--even if I use the path that TypeDoc outputs in console (@org/foo.folder/fooFolderModule.foo).

[jviall]

@Gerrit0 curious to hear your thoughts!

[jviall]

@Gerrit0 I was able to get the reference working with the full path:

/**
* {@link @org/foo!folder/module.Foo}
*/

But it seems like we should still be able to use the short-hand of @org/foo!Foo, and it feels like a bug that it's not working?

[Gerrit0]

Declaration references will not magically skip levels of your hierarchy to find child symbols, that's working as expected, not a bug, they're intended to be suitable for unambiguously defining references to symbols. If TypeDoc allowed skipping levels it would also have to check for and warn about ambiguous links, which would be both expensive and even more obnoxious to debug than the current link resolution.

Personally, I do not recommend documenting entire project trees like you have it set up to do, and instead have a file responsible for re-exporting the public members of your library, and pointing TypeDoc (and your users!) at that; which makes it simpler to use and also simpler to document.

the only difference is that the @org/foo project has a @org/foo/src/fooModule.ts file, which I assume changes the resulting reference path that TypeDoc generates for @org/foo.folder/fooFolderModule.foo?

There's a combination of two things here which play together.

1. TypeDoc derives the root path for a module from your entry points (unless provided with basePath)
2. When only one entry point is provided, TypeDoc will skip creating a child module (unless alwaysCreateEntryPointModule is specified)

In this case since you have one file, TypeDoc is adding the exports of @org/baz directly to that project, while the projects with more than one entry point need modules created, whose names are relative to the derived basePath of the project.