Third-Party symbol not resolved in @link

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]

Published! https://typedoc.org/guides/options/#externalsymbollinkmappings

[danielwiehl]

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!