TypeStrong/typedoc

Third-Party symbol not resolved in @link

danielwiehl opened this issue · 5 comments

danielwiehl commented

Search terms

link; link to third-party symbol; third-party symbol; will break in v0.24

Question

We generate API documentation for a library that heavily depends on a third-party library. In many comments, we refer to types of that third-party library using the link tag, e.g., {@link Session}.

When generating the documentation, for every link to the third-party library, we get an error like Failed to resolve {@link Session} in ... with declaration references. This link will break in v0.24. That makes sense since TypeDoc has no idea where to find the respective documentation site. We learned that we could write a custom TypeDoc plugin similar to the MDN link plugin for providing a mapping for our third-party symbols. But, it turned out that this only works for symbols referenced in code but not for symbols referenced in links via the @link tag.

Below an example. The MessageClient class references the third-party symbol Session both by link and in the constructor.

import {Session} from 'solclientjs';

/**
 * See {@link Session} for more information.  // will not be resolved
  */
export class MessageClient {

  constructor(session: Session) { // will be resolved if writing a custom TypeDoc plugin that adds a resolver for the unknown symbol `Session`
  }
}

Did we miss something?

Also, having to write a custom TypeDoc plugin for solely providing associations of third-party symbols to their documentation site seems very cumbersome. Isn't there a way to configure the mappings directly in tsconfig.json under typedocOptions? That would be so straightforward, sort of like this. What do you think about it?

    "typedocOptions": {
      ... omitted
      "validation": {
        "invalidLink": true
      },
      "externalSymbolLinkMappings": { // something like this would be great to not have to write a custom TypeDoc plugin
        "solclientjs": {
          "Session": "https://docs.solace.com/API-Developer-Online-Ref-Documentation/js/solace.Session.html"
        }
      }
    }
Gerrit0 commented

No, you didn't miss anything. Since Session isn't actually included in your documentation, TypeDoc can't resolve it to a real link.

@links are resolved with declaration references, and do not take into consideration what symbols you have in scope at the location the @link tag is declared. This is a difference to how VSCode resolves links, but means that links do not have the potential for changing depending on if you run on your .ts files or compiled .d.ts files. (And, the aim for 0.24 is generation from previously created json outputs, so we won't have that info then)

Letting plugins add resolvers for external {@link} tags seems like a good idea, doing that would make the following work:

/**
 * See {@link solclientjs!Session} for more information.
  */
export class MessageClient {}

I like the idea of externalSymbolLinkMappings for one off additions. The main reason I went for plugin based resolution is that they can be easily shared across projects, and there are ridiculous numbers of links for some libraries, (typedoc-plugin-mdn-links has ~500)

danielwiehl commented

Thank you @Gerrit0 for the detailed explanation and for marking this as an enhancement I would like to see in a future release:-)

Gerrit0 commented

These docs will be added to the website as well on release - but too late for that tonight, do you think this will meet your use case? https://github.com/TypeStrong/typedoc/blob/master/internal-docs/third-party-symbols.md#third-party-symbols

danielwiehl commented

These docs will be added to the website as well on release - but too late for that tonight, do you think this will meet your use case? https://github.com/TypeStrong/typedoc/blob/master/internal-docs/third-party-symbols.md#third-party-symbols

@Gerrit0 Great, this is precisely what we were looking for and will cover our use case. Thank you very much!

  • 👍1