Display `@deprecated` doc when available

We need to display documentation associated with the @deprecated tag when available.

Currently we are only displaying the tag on a page, and the documentation is being "scrubbed". For example: https://deno.land/api@v1.25.4?s=Deno.iterSync which looks like this in JSDoc:

declare namespace Deno {
/**
   * Turns a ReaderSync, `r`, into an iterator.
   *
   * ```ts
   * let f = Deno.openSync("/etc/passwd");
   * for (const chunk of Deno.iterSync(f)) {
   *   console.log(chunk);
   * }
   * f.close();
   * ```
   *
   * Second argument can be used to tune size of a buffer.
   * Default size of the buffer is 32kB.
   *
   * ```ts
   * let f = await Deno.open("/etc/passwd");
   * const iter = Deno.iterSync(f, {
   *   bufSize: 1024 * 1024
   * });
   * for (const chunk of iter) {
   *   console.log(chunk);
   * }
   * f.close();
   * ```
   *
   * Iterator uses an internal buffer of fixed size for efficiency; it returns
   * a view on that buffer on each iteration. It is therefore caller's
   * responsibility to copy contents of the buffer if needed; otherwise the
   * next iteration will overwrite contents of previously returned chunk.
   *
   * @deprecated Use `iterateReaderSync` from
   * https://deno.land/std/streams/conversion.ts instead. `Deno.iterSync` will
   * be removed in Deno 2.0.
   *
   * @category I/O
   */
  export function iterSync(
    r: ReaderSync,
    options?: {
      bufSize?: number;
    },
  ): IterableIterator<Uint8Array>;
}

denoland / dotland

Display `@deprecated` doc when available #2509