Skip to content

Fix links stripped from docs during Typedoc link resolution #1304

@pokey

Description

@pokey

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions