-
-
Notifications
You must be signed in to change notification settings - Fork 91
Description
As part of #1281, we upgraded Typedoc to 0.23.x. That version of Typedoc includes a new link resolution algorithm for JSDocs that include {@link ...} links. Unfortunately, that new algorithm doesn't match the way that VSCode resolves links, resulting in links being dropped in our auto-generated API documentation. These broken links are indicated in #942 (comment)
This issue should be fixed on 0.24.0 (see TypeStrong/typedoc#2197 and TypeStrong/typedoc#2141), so we should try to upgrade.
I made an initial attempt to upgrade to 0.24.0, but couldn't get things working. A couple plugins were outdated, and it looks like cross-package links broke. When I tried to fix cross-package links using the new packages setting designed for monorepos, I got the following output and gave up:
[INFO] Starting the development server...
[info] Converting project at /Users/pokey/src/cursorless/packages/cheatsheet
[error] Unable to find any entry points. Make sure TypeDoc can find your tsconfig
[info] Converting project at /Users/pokey/src/cursorless/packages/cheatsheet-local
[info] Converting project at /Users/pokey/src/cursorless/packages/common
[info] Converting project at /Users/pokey/src/cursorless/packages/cursorless-engine
[info] Converting project at /Users/pokey/src/cursorless/packages/cursorless-org
[info] Converting project at ./
[error] Project at ./ has entryPointStrategy set to packages, but nested packages are not supported.
[info] Converting project at /Users/pokey/src/cursorless/packages/cursorless-vscode
[info] Converting project at /Users/pokey/src/cursorless/packages/cursorless-vscode-core
[info] Converting project at /Users/pokey/src/cursorless/packages/cursorless-vscode-e2e
[info] Converting project at /Users/pokey/src/cursorless/packages/meta-updater
[info] Converting project at /Users/pokey/src/cursorless/packages/test-harness
[info] Converting project at /Users/pokey/src/cursorless/packages/vscode-common
[info] Merging converted projects
[error] Failed to convert one or more packages, result will not be merged together.
Here's a tag with my attempt for future use. Should be able to:
git fetch
git switch -c typedoc-24-0 pokey/initial-failed-typedoc-0-24-0-attempt
pnpm up -rL '*typedoc*'I do wonder how much value these api docs are providing, though. We're not really using typedoc as intended: it's supposed to be for documenting api's for public libraries, and we're trying to use it to document all of our internal code for our contributors, where arguably it might be better to just let our contributors have guided walk throughs of the source code itself