denoland / deno_doc

Documentation generator for Deno
MIT License
253 stars 54 forks source link

[HTML] `@link` and `@linkcode` tags are not processed correctly on all symbols page #594

Open nberlette opened 3 months ago

nberlette commented 3 months ago

Deno Version

$ deno --version

deno 1.43.6+53606de (canary, x86_64-apple-darwin)
v8 12.6.228.3
typescript 5.4.5

Expected Behavior

The @linkcode and @link tags in symbol descriptions should generate a link with and without a <code> tag around the specified text, respectively.

This provides clear and navigable links within the documentation. Since the individual symbol pages handle these JSDoc tags as expected, I would also expect for the "all symbols" page to do the same.

Actual Behavior

The @link and @linkcode tags are not handled correctly on the "all symbols" pages, and end up rendered without any hyperlink at all, and two instances of the linked symbol name.

For example, {@link TrimLeft} renders as TrimLeft | TrimLeft, and {@linkcode TrimLeft} renders as <code>TrimLeft</code> | TrimLeft (with no links in either).

All Symbols

image

Individual Symbol

image

Documented Code

This is the code that the documentation was generated from in the above screenshots:

/**
 * See {@link TrimLeft} for the type equivalent. See {@linkcode TrimLeft}
 * for the type equivalent.
 */
export function trimLeft(value: string): string {
  return value.replace(/^\s+/, "");
}

/**
 * See {@link trimLeft} for the runtime equivalent. See {@linkcode trimLeft} 
 * for the runtime equivalent.
 */
export type TrimLeft = (value: string) => string;

Thanks for your time.

crowlKats commented 3 months ago

We have a patch that already landed (#580) that fixes the high-level issue that its rendered double. however linking itself is a separate issue thats trickier, and has a todo: https://github.com/denoland/deno_doc/blob/b238c88caac7200646262b8f07117c6601a5dff6/src/html/pages.rs#L175