wrong property being resolved when using {@link type#property}

[techfg]

This issue stems out of TypeStrong/typedoc#2808.

When linking to a property of a type deriving from ZodObject, links to properties appear to be resolved to incorrect properties resulting in the wrong link being emitted.

Repro: https://stackblitz.com/edit/vitejs-vite-27sucs62?file=src%2Findex.ts

npm run docs

In the below errors, it appears to be taking the resolution one property too far. For example:

   * Link to Options.collections property - {@link Options#collections collections}

appears to give an error of which references Options.collections.base but the link points to Options.collections

[warning] "CollectionConfig" links to "Options.__type.collections.__type.base" with text "base1" which exists but does not have a link in the documentation, will link to "Options.__type.collections" instead.

Note that the problem does not happen if this line is replaced with this line.

Full Error Log:

[warning] "CollectionConfig" links to "Options.__type.collections.__type.base" with text "base1" which exists but does not have a link in the documentation, will link to "Options.__type.collections" instead.
[warning] "CollectionConfig" links to "Options.__type.collections.__type.name" with text "name1" which exists but does not have a link in the documentation, will link to "Options.__type.collections" instead.
[warning] "Options" links to "Options.__type.collections.__type.base" with text "base2" which exists but does not have a link in the documentation, will link to "Options.__type.collections" instead.
[warning] "Options" links to "Options.__type.collections.__type.name" with text "name2" which exists but does not have a link in the documentation, will link to "Options.__type.collections" instead.
[warning] "default" links to "Options.__type.collections.__type.base" with text "base2" which exists but does not have a link in the documentation, will link to "Options.__type.collections" instead.
[warning] "default" links to "Options.__type.collections.__type.name" with text "name2" which exists but does not have a link in the documentation, will link to "Options.__type.collections" instead.

[Gerrit0]

This is working as designed. How those links are resolved is dependent on the order in which the reflections are created, which is a design limitation of TypeDoc.

If you swap the export order so that CollectionConfig is exported before Options, then it will be converted first, and so links targeting those properties will go to that property rather than being resolved within the Options type.

[techfg]

Thanks @Gerrit0!

Did not realize order mattered - sure enough, swapping the order resolves the issue, thank you!

Unfortunately, when the types are actually in a separate file and then imported/exported from index, a different error is encountered.

Repro: https://stackblitz.com/edit/vitejs-vite-tc7hge5k?file=src%2Findex.ts

For example, the following:

   * Link to Options.collections property - {@link Options#collections collections1}

results in the error:

[warning] "CollectionConfig" links to "default.opts.__type.collections" with text "collections1" which exists but does not have a link in the documentation, will link to "default" instead.

Where it seems like the link is trying to resolve to the default export parameter instead of the Options type itself.

Hopefully this is just a simple user error again :)

Let me know your thoughts and/or if you prefer I open a different issue for this one.

Full Error Log:

[warning] "CollectionConfig" links to "default.opts.__type.collections" with text "collections1" which exists but does not have a link in the documentation, will link to "default" instead.
[warning] "CollectionConfig" links to "default.opts.__type.collectionBase" with text "collectionBase1" which exists but does not have a link in the documentation, will link to "default" instead.
[warning] "CollectionConfig" links to "default.opts.__type.collections.__type.base" with text "base1" which exists but does not have a link in the documentation, will link to "default" instead.
[warning] "CollectionConfig" links to "default.opts.__type.collections.__type.name" with text "name1" which exists but does not have a link in the documentation, will link to "default" instead.
[warning] "Options" links to "default.opts.__type.collections" with text "collections2" which exists but does not have a link in the documentation, will link to "default" instead.
[warning] "Options" links to "default.opts.__type.collectionBase" with text "collectionBase2" which exists but does not have a link in the documentation, will link to "default" instead.
[warning] "Options" links to "default.opts.__type.collections.__type.base" with text "base2" which exists but does not have a link in the documentation, will link to "default" instead.
[warning] "Options" links to "default.opts.__type.collections.__type.name" with text "name2" which exists but does not have a link in the documentation, will link to "default" instead.
[warning] "default" links to "default.opts.__type.collections" with text "collections2" which exists but does not have a link in the documentation, will link to "default" instead.
[warning] "default" links to "default.opts.__type.collectionBase" with text "collectionBase2" which exists but does not have a link in the documentation, will link to "default" instead.
[warning] "default" links to "default.opts.__type.collections.__type.base" with text "base2" which exists but does not have a link in the documentation, will link to "default" instead.
[warning] "default" links to "default.opts.__type.collections.__type.name" with text "name2" which exists but does not have a link in the documentation, will link to "default" instead.

Thanks!

[techfg]

Using your input about how order matters, if I change entryPoints to include both entry points explicitly and remove the export of the types from index, everything generates as expected, no errors.

Doing this though results in separate modules so I applied mergeModuleWith to consolidate into a unified doc.

Not sure if this is the correct way to accomplish the end-state goal or if there's a simpler solution to workaround the issue mentioned in prior comment I posted or if the prior comment indicates a bug/issue to begin with?

Repro: https://stackblitz.com/edit/vitejs-vite-z2zzkmkp?file=src%2Findex.ts%3AL3,src%2Fstuff.ts,typedoc.json%3AL4

Thanks!

[Gerrit0]

There's basically no good answer here...

Zod's types are constructed such that TypeScript expands them incredibly eagerly. Your default export so far as the types are concerned basically ignores the type alias, which causes this:

Because of this, those properties get assigned the symbols first, so TypeDoc tries to link to that. The logic I added in typedoc apparently didn't include prioritization of type alias properties, which would also fix this issue... Added with TypeStrong/typedoc@23008f6

TypeDoc converts direct exports first, followed by re-exports, so default is being converted first. Moving it to another file and converting works like you'd expect:

export * from "./stuff.js";
export { default } from "./fn.js";

[techfg]

Incredibly helpful, thank you!

Confirmed that using the current master branch which includes TypeStrong/typedoc@23008f6 and no other changes to the repro resolves the link trying to resolve to default.opts....!

Also confirmed that moving to separate fn.js and exporting from index as you suggest avoids the need for @mergeModuleWith!

Zod's types are constructed such that TypeScript expands them incredibly eagerly. Your default export so far as the types are concerned basically ignores the type alias, which causes this:

I think I know the answer to this but....is there any way to make it such that the docs do not use the expanded type and instead simply reference the Options type itself like it would do if Options were an interface?

[Gerrit0]

The type that TypeDoc sees when converting opts is the type you see when hovering over the parameter, which is the expanded one, not the alias name.... I spent a half an hour or so poking around just now and don't see a way to get the alias back once TS decides to expand it here.

Personally, I'd lean towards using interfaces, and use @expand if you want the declaration expanded somewhere in the docs.

[techfg]

Based on your input previously, didn't think it was going to be possible but really appreciate you giving it a go!

Agreed on leaning toward interfaces. The only hang-up I have is that in vscode, when hovering over the type, you get interface Options instead of the expanded props. Solving this requires having Options be a type. I could use @interface on the type to get the docs the way I want but seems weird/incorrect to have the docs show it as an interface when it's really a type.