Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[SDK-4011] Fix broken link text in generated documentation #1601

Merged
merged 2 commits into from
Feb 15, 2024
Merged

[SDK-4011] Fix broken link text in generated documentation #1601

merged 2 commits into from
Feb 15, 2024

Commits on Jan 29, 2024

  1. Remove public ChannelModes type 

    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.
    @lawrence-forooghian
    lawrence-forooghian committed Jan 29, 2024
    Configuration menu
    Copy the full SHA
    04f0f16 View commit details
    Browse the repository at this point in the history

  2. Remove duplicate type names 

    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
    lawrence-forooghian committed Jan 29, 2024
    Configuration menu
    Copy the full SHA
    f7e28aa View commit details
    Browse the repository at this point in the history