Option to keep full name in {@link} output

[jonchardy]

Search Terms

link

Problem

We have many links in our documentation, some which link to members on the same page, others which link to other pages.

{@link foo}
{@link Bar.baz}

Currently, the Bar.baz link is shortened to just baz in the output, which is less informative when linking to another class. It would be nice if there was an option to allow {@link} tags to keep the full name in output.

This also doesn't appear to be easy to change with a plugin since the InlineDisplayTag.text is set in https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/comments/linkResolver.ts. That means it's hard to determine the original link text if you wanted to get the full name from the InlineDisplayTag.target.

Maybe it could be done with a plugin that appended a '|' to all links including '.'? Massaging input like that doesn't seem great though.

Suggested Solution

Add an option, maybe 'fullNameLinks', that keeps the full name if the @link tag includes '.' or '#'.

[jonchardy]

For now, I've worked around this like so:

export class MyPlugin {
  initialize(app: Application) {
    // retain full link names
    app.converter.on(
      Converter.EVENT_RESOLVE_END,
      (context: Context) => {
        const project = context.project;
        for (const reflection of Object.values(project.reflections)) {
          if (reflection.comment) {
            MyPlugin.expandLinks(reflection.comment, reflection);
          }
        }
      }
    );
  }

  /**
   * Save full friendly name as tsLinkText so we can retain full name links.
   * This prevents links like "Foo.bar" from rendering as just "bar".
   * Only applies to links that include "." or "#", not local links.
   * Does not apply to links including "|", which indicates another name is supplied.
   * @param comment
   * @param reflection
   */
  static expandLinks(comment: Comment, reflection: Reflection) {
    function mapParts(parts: CommentDisplayPart[]) {
      return parts.flatMap((part) => {
        if (part.kind === "inline-tag" &&
            (part.tag === "@link" || part.tag === "@linkcode" || part.tag === "@linkplain") &&
            (part.text.includes('.') || part.text.includes('#')) &&
            !part.text.includes('|') &&
            part.target instanceof ReflectionSymbolId) {
          const tsTarget = reflection.project.getReflectionFromSymbolId(part.target);
          if (tsTarget) part.tsLinkText = tsTarget.getFriendlyFullName();
        }
        return part;
      });
    }

    comment.summary = mapParts(comment.summary);
    for (const tag of comment.blockTags) {
      tag.content = mapParts(tag.content);
    }
  }
}

This assumes the links are well-formed and useTsLinkResolution is being used.

[Gerrit0]

It also assumes that all @links are within the same project if running with --entryPointStrategy packages

I think this is a reasonable option to add, maybe also as default behavior...