Display and link to `Throws` types

[jack5github]

Search Terms

aliases, errors, exceptions, html, href, links, linking, parsing, signatures, throws, titles, type aliases, types, typography

Problem

Currently, error types are not displayed in typedoc exports. Additionally, errors are displayed in separated blocks of text, when it is possible for there to be multiple of them, which suggests that they should be presented in the same structure as parameters.

Suggested Solution

Referenced error types in docstrings should be shown in the doctype export, in the same way as parameters, for example:

/**
 * @param {string} arg1 A string argument.
 * @param {number} arg2 An integer argument.
 * @returns {Promise<void>} A Promise that resolves when the function is complete.
 * @throws {TypeError} If `arg1` is not a string.
 * @throws {TypeError} If `arg2` is not an integer.
 * @throws {RangeError} If `arg2` being used as an index on `arg1` is out of bounds.
 * @throws {CustomExportedError} If unable to get the accumulator value.
 */

...should become:

<div class="tsd-parameters">
  <h4 class="tsd-parameters-title">Parameters</h4>
  <ul class="tsd-parameter-list">
    <li>
      <span><span class="tsd-kind-parameter">arg1</span>: <span class="tsd-signature-type">string</span></span>
      <div class="tsd-comment tsd-typography"><p>A string argument.</p></div>
    </li>
    <li>
      <span><span class="tsd-kind-parameter">arg2</span>: <span class="tsd-signature-type">number</span></span>
      <div class="tsd-comment tsd-typography"><p>An integer argument.</p></div>
    </li>
  </ul>
</div>
<h4 class="tsd-returns-title">Returns <span class="tsd-signature-type">Promise</span><span class="tsd-signature-symbol">&lt;</span><span class="tsd-signature-type">void</span><span class="tsd-signature-symbol">&gt;</span></h4>
<p>A Promise that resolves when the function is complete.</p>
<!-- The below is what may appear when this issue is resolved. Note the unordered list format and linked error types. -->
<div class="tsd-throws">
  <h4 class="tsd-throws-title">Throws</h4>
  <ul class="tsd-throws-list">
    <li>
      <span><span class="tsd-signature-type">TypeError</span></span>
      <div class="tsd-comment tsd-typography"><p>If <code>arg1</code> is not a string.</p></div>
    </li>
    <li>
      <span><span class="tsd-signature-type">TypeError</span></span>
      <div class="tsd-comment tsd-typography"><p>If <code>arg2</code> is not an integer.</p></div>
    </li>
    <li>
      <span><span class="tsd-signature-type">RangeError</span></span>
      <div class="tsd-comment tsd-typography"><p>If <code>arg2</code> being used as an index on <code>arg1</code> is out of bounds.</p></div>
    </li>
    <li>
      <span><a href="..." class="tsd-signature-type tsd-kind-type-alias">CustomExportedError</a></span>
      <div class="tsd-comment tsd-typography"><p>If unable to get the accumulator value.</p></div>
    </li>
  </ul>
</div>

[Gerrit0]

Fixing this is somewhat obnoxious as CommentTag does not preserve sufficient information.

Help wanted. I think the appropriate path for this for now is to change CommentTag.typeAnnotation to be a type instead of just the string. This will be a breaking change, so will have to be a minor update, but that's fine. I need to do that at some point to drop Node 18 support anyways.

Once that is done, @throws will have to be added to the default list of preserved annotations, then the renderer updated to do custom rendering. Not quite a trivial feature, but a good one for someone looking to get familiar with many different parts of TypeDoc's codebase.