typedoc
typedoc copied to clipboard
TypeStrong
Cross-package references in monorepository not working
Search terms
monorepository entrypointStrategy packages reference
Expected Behavior
Cross-package references should "work" when generating documentation for several packages in a monorepository (using yarn workspaces), with an entrypointStrategy set to packages.
Actual Behavior
Cross-package references yield a warning:
A, defined at packages/a/lib/index.d.ts:3, is referenced by @typedoc-packages-missing-export/b.B.__type.a but not included in the documentation.
And the resulting documentation does not have hyperlinks for such references.
Steps to reproduce the bug
Here is an example repository to reproduce the bug: https://github.com/nlepage/typedoc-packages-missing-export
Environment
- Typedoc version: 0.22.10
- TypeScript version: 4.5.4
- Node.js version: 14.17.0
- OS: Linux
I'm willing to help resolve the issue, however I don't have enough knowledge of TypeDoc in order to guess where to start looking.
This happens for the same reason it happens with project references. TypeDoc creates a new program for each monorepo, and symbols between programs are completely separate... but references are resolved by symbol equality.
I think this could be resolved by changing symbols so that they are compared by source location (with mapping... so declarationMap would have to be turned on), but haven't gotten around to trying to make that work yet.
Hey @Gerrit0
I made a plugin to solve the problem: nlepage/typedoc-plugin-resolve-crossmodule-references.
Not sure about all of it, but it works fine for the basic cases.
Here is an example of generated documentation where types from a module a reference a type B from a module b.
It is published on npm.
I'm not sure if it can help with project references as I'm not familiar with these.
Let me know if it is something you would like to integrate in TypeDoc itself. It needs only one new dependency (plus a transitive one): convert-source-map.
I think that's definitely a promising path forward! I'm probably not going to have time this weekend to look at it in as much detail as it deserves, but it's something I'm absolutely interested in pursuing. I'd like to avoid the extra resolution step if possible, (by storing reference targets by file/location?)
I've run into some issues with shared type reference resolving inproperly. I wonder if it may be related to this issue. Somehow in my case in certain scenarios shared types are excluded from build, log output below seems to support my observation.
Warning: Resource, defined at shared/index.d.ts:1716, is referenced by alt-server.Resource.all but not included in the documentation.
Warning: InterfaceValueByKey, defined at shared/index.d.ts:919, is referenced by alt-client.on.on.listener but not included in the documentation.
Warning: InterfaceValueByKey, defined at shared/index.d.ts:919, is referenced by alt-server.on.on.listener but not included in the documentation.
Reproduceable in https://github.com/altmp/altv-types repo (officially old TypeDoc version is used still, but above log output comes from v0.22.13). Help me out by telling me if these cases are connected or not
@nlepage Are there any prerequisite I need to know or settings made to get your plugin working? I just installed and tried but unfortunately it did not work for me :(
@nlepage Are there any prerequisite I need to know or settings made to get your plugin working? I just installed and tried but unfortunately it did not work for me :(
Hey @phihochzwei
Seems the plugin I wrote crashes with the latest version of typedoc, as a workaround you can try downgrading typedoc to v0.22.18.
I'll try to fix the plugin to make it work with the latest version of typedoc.
@nlepage Are there any prerequisite I need to know or settings made to get your plugin working? I just installed and tried but unfortunately it did not work for me :(
@phihochzwei I published a new release of the plugin, let me know if it works for you.
At this point, yes. I'm getting somewhat closer to bringing this functionality into TypeDoc itself, but that will be a part of 0.24 most likely.
@nlepage Just wanted to mention the plugin works great for me, thanks. :) Except that it doesn't identify the @link references to other modules for me unfortunately.
@Tschakki I'll have a look, could you open an issue on the plugin's repository thanks https://github.com/nlepage/typedoc-plugin-resolve-crossmodule-references
v0.24.0 made a ton of changes, including a fix for this. Types are now serialized with their location rather than relying on object identity, and therefore can be resolved even across packages
v0.24.0 made a ton of changes, including a fix for this. Types are now serialized with their location rather than relying on object identity, and therefore can be resolved even across packages
I don't think it's working. U can check this table using the plugin in older version of typedoc https://tagscript.js.org/typedoc-api/plugins/plugin-discord/classes/BaseTransformer#parameters-1 vs current one https://tag-script-git-renovate-all-minor-patch-imranbarbhuiya.vercel.app/typedoc-api/plugins/plugin-discord/classes/BaseTransformer#parameters-1
Also an unrelated issue so lmk if I should create a new issue for this but when using links like {@link discord.js!}, and adding it's link using typedoc-plugin-external-link, it works but tsdoc eslint warns about using ! also it renders the ! in final website too but removing ! doesn't works and tsdoc warns that the link wasn't resolved
I'm going to have to ask for a new issue with a minimal reproduction for both of those. I don't have time to dig through big projects for a bug.
I'm going to have to ask for a new issue with a minimal reproduction for both of those. I don't have time to dig through big projects for a bug.
Thanks for all your hard work.
typedoc-plugin-resolve-crossmodule-references is now archived and deprecated on npm, thanks for all your hard work @Gerrit0 !