[SDK-4011] Fix broken link text in generated documentation #1601
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
It doesn’t add any value, is inconsistent (we don’t create any other types for arrays), and I want to introduce a different type with the same name.
github-actions
bot
temporarily deployed
to
staging/pull/1601/features
github-actions
bot
temporarily deployed
to
staging/pull/1601/typedoc
github-actions
bot
temporarily deployed
to
staging/pull/1601/bundle-report
We were using TypeDoc’s declaration reference functionality [1] to disambiguate these, but this broke when we upgraded TypeDoc in 5f69795 — it started generating link text of ":type" instead of the name of the type. This is because TypeDoc 0.24 added the --useTsLinkResolution option, which is on by default. This option parses @link tags using the TypeScript compiler. It does this in order to more closely match the way in which editors such as VS Code will handle @link tags. However, the TypeScript compiler’s parsing does not support TypeDoc declaration syntax (and does not offer its own alternative), only falling back to TypeDoc @link parsing when TypeScript fails to parse a @link. (See the TypeDoc issue I raised [2] for further context.) So, stop using declaration references to disambiguate types. We still make some use of declaration references in modules.d.ts, to link to the types in ably.d.ts and to link to a specific overload of a method. These are still being parsed correctly (because TypeScript is unable to parse them) and there is no good alternative, so I’ll leave them as is, accepting that editors won’t handle them well (as was always the case). Resolves #1560. [1] https://typedoc.org/guides/declaration-references/ [2] TypeStrong/typedoc#2485
lawrence-forooghian
force-pushed
the
1560-fix-typedoc-links
branch
from
85dabd5
to
f7e28aa
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Resolves #1560, in which upgrading TypeDoc caused some link text in the generated HTML documentation to become incorrect. See commit messages for more details.