docs: replace markdown hyperlink syntax with {@link} tag where nece…

…ssary. (denoland#4253)

docs: replaces markdown hyperlink syntax with `{@link}` tag when necessary.

cli/parse_args.ts

@@ -3,7 +3,7 @@
 
 /**
  * Command line arguments parser based on
- * [minimist](https://github.com/minimistjs/minimist).
+ * {@link https://github.com/minimistjs/minimist | minimist}.
  *
  * This module is browser compatible.
  *
@@ -375,7 +375,8 @@ function hasKey(obj: NestedMapping, keys: string[]): boolean {
   return key !== undefined && hasOwn(o, key);
 }
 
-/** Take a set of command line arguments, optionally with a set of options, and
+/**
+ * Take a set of command line arguments, optionally with a set of options, and
  * return an object representing the flags found in the passed arguments.
  *
  * By default, any arguments starting with `-` or `--` are considered boolean

crypto/mod.ts

@@ -3,7 +3,7 @@
 
 /**
  * Extensions to the
- * [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API)
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API | Web Crypto}
  * supporting additional encryption APIs, but also delegating to the built-in
  * APIs when possible.
  *

crypto/timing_safe_equal.ts

@@ -11,7 +11,7 @@ import { assert } from "../assert/assert.ts";
  *
  * It is likely some form of timing safe equality will make its way to the
  * WebCrypto standard (see:
- * [w3c/webcrypto#270](https://github.com/w3c/webcrypto/issues/270)), but until
+ * {@link https://github.com/w3c/webcrypto/issues/270 | w3c/webcrypto#270}), but until
  * that time, `timingSafeEqual()` is provided:
  *
  * ```ts

crypto/unstable_keystack.ts

@@ -46,7 +46,8 @@ function sign(data: Data, key: CryptoKey): Promise<ArrayBuffer> {
   return crypto.subtle.sign("HMAC", key, data);
 }
 
-/** Compare two strings, Uint8Arrays, ArrayBuffers, or arrays of numbers in a
+/**
+ * Compare two strings, Uint8Arrays, ArrayBuffers, or arrays of numbers in a
  * way that avoids timing based attacks on the comparisons on the values.
  *
  * The function will return `true` if the values match, or `false`, if they
@@ -67,12 +68,13 @@ async function compare(a: Data, b: Data): Promise<boolean> {
   return timingSafeEqual(ah, bh);
 }
 
-/** A cryptographic key chain which allows signing of data to prevent tampering,
+/**
+ * A cryptographic key chain which allows signing of data to prevent tampering,
  * but also allows for easy key rotation without needing to re-sign the data.
  *
  * Data is signed as SHA256 HMAC.
  *
- * This was inspired by [keygrip](https://github.com/crypto-utils/keygrip/).
+ * This was inspired by {@link https://github.com/crypto-utils/keygrip/ | keygrip}.
  *
  * @example
  * ```ts
@@ -101,7 +103,8 @@ export class KeyStack {
     return this.#keys.length;
   }
 
-  /** A class which accepts an array of keys that are used to sign and verify
+  /**
+   * A class which accepts an array of keys that are used to sign and verify
    * data and allows easy key rotation without invalidation of previously signed
    * data.
    *
@@ -116,24 +119,30 @@ export class KeyStack {
     this.#keys = values;
   }
 
-  /** Take `data` and return a SHA256 HMAC digest that uses the current 0 index
+  /**
+   * Take `data` and return a SHA256 HMAC digest that uses the current 0 index
    * of the `keys` passed to the constructor.  This digest is in the form of a
-   * URL safe base64 encoded string. */
+   * URL safe base64 encoded string.
+   */
   async sign(data: Data): Promise<string> {
     const key = await this.#toCryptoKey(this.#keys[0]);
     return encodeBase64Url(await sign(data, key));
   }
 
-  /** Given `data` and a `digest`, verify that one of the `keys` provided the
+  /**
+   * Given `data` and a `digest`, verify that one of the `keys` provided the
    * constructor was used to generate the `digest`.  Returns `true` if one of
-   * the keys was used, otherwise `false`. */
+   * the keys was used, otherwise `false`.
+   */
   async verify(data: Data, digest: string): Promise<boolean> {
     return (await this.indexOf(data, digest)) > -1;
   }
 
-  /** Given `data` and a `digest`, return the current index of the key in the
+  /**
+   * Given `data` and a `digest`, return the current index of the key in the
    * `keys` passed the constructor that was used to generate the digest.  If no
-   * key can be found, the method returns `-1`. */
+   * key can be found, the method returns `-1`.
+   */
   async indexOf(data: Data, digest: string): Promise<number> {
     for (let i = 0; i < this.#keys.length; i++) {
       const cryptoKey = await this.#toCryptoKey(this.#keys[i]);

csv/stringify.ts

@@ -111,7 +111,7 @@ export type StringifyOptions = {
   columns?: Column[];
   /**
    * Whether to add a
-   * [byte-order mark](https://en.wikipedia.org/wiki/Byte_order_mark) to the
+   * {@link https://en.wikipedia.org/wiki/Byte_order_mark | byte-order mark} to the
    * beginning of the file content. Required by software such as MS Excel to
    * properly display Unicode text.
    *

dotenv/mod.ts

@@ -103,8 +103,8 @@ export function loadSync(
  * in a configuration object returned by the `load()` function, as well as optionally
  * exporting them to the process environment using the `export` option.
  *
- * Inspired by the node modules [`dotenv`](https://github.com/motdotla/dotenv)
- * and [`dotenv-expand`](https://github.com/motdotla/dotenv-expand).
+ * Inspired by the node modules {@linkcode https://github.com/motdotla/dotenv | dotenv}
+ * and {@linkcode https://github.com/motdotla/dotenv-expand | dotenv-expand}.
  *
  * ## Basic usage
  * ```sh
@@ -252,7 +252,7 @@ export function loadSync(
  * - inner quotes are maintained (think JSON) (`JSON={"foo": "bar"}` becomes
  *   `{ JSON: "{\"foo\": \"bar\"}" }`)
  * - whitespace is removed from both ends of unquoted values (see more on
- *   [`trim`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/Trim))
+ *   {@linkcode https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/Trim | trim})
  *   (`FOO= some value` becomes `{ FOO: "some value" }`)
  * - whitespace is preserved on both ends of quoted values (`FOO=" some value "`
  *   becomes `{ FOO: " some value " }`)

expect/mod.ts

@@ -3,21 +3,8 @@
 // This module is browser compatible.
 
 /**
- * @module
- *
  * This module provides jest compatible expect assertion functionality.
  *
- * @example
- * ```ts
- * import { expect } from "https://deno.land/std@$STD_VERSION/expect/mod.ts";
- *
- * const x = 6 * 7;
- * expect(x).toEqual(42);
- * expect(x).not.toEqual(0);
- *
- * await expect(Promise.resolve(x)).resolves.toEqual(42);
- * ```
- *
  * Currently this module supports the following matchers:
  * - `toBe`
  * - `toEqual`
@@ -81,8 +68,20 @@
  * - `expect.addSnapshotSerializer`
  * - `expect.extend`
  *
- * This module is largely inspired by [x/expect](https://github.com/allain/expect) module by Allain Lalonde.
+ * This module is largely inspired by {@link https://github.com/allain/expect | x/expect} module by Allain Lalonde.
+ *
+ * @example
+ * ```ts
+ * import { expect } from "https://deno.land/std@$STD_VERSION/expect/mod.ts";
+ *
+ * const x = 6 * 7;
+ * expect(x).toEqual(42);
+ * expect(x).not.toEqual(0);
+ *
+ * await expect(Promise.resolve(x)).resolves.toEqual(42);
+ * ```
+ *
+ * @module
  */
-
 export { expect } from "./expect.ts";
 export { fn } from "./fn.ts";

flags/mod.ts

@@ -3,7 +3,7 @@
 
 /**
  * Command line arguments parser based on
- * [minimist](https://github.com/minimistjs/minimist).
+ * {@link https://github.com/minimistjs/minimist | minimist}.
  *
  * This module is browser compatible.
  *
@@ -388,7 +388,8 @@ function hasKey(obj: NestedMapping, keys: string[]): boolean {
   return key !== undefined && hasOwn(o, key);
 }
 
-/** Take a set of command line arguments, optionally with a set of options, and
+/**
+ * Take a set of command line arguments, optionally with a set of options, and
  * return an object representing the flags found in the passed arguments.
  *
  * By default, any arguments starting with `-` or `--` are considered boolean

front_matter/mod.ts

@@ -3,14 +3,14 @@
 
 /**
  * Extracts
- * [front matter](https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/)
+ * {@link https://daily-dev-tips.com/posts/what-exactly-is-frontmatter/ | front matter}
  * from strings.
  *
  * {@linkcode createExtractor} and {@linkcode test} functions
  * to handle many forms of front matter.
  *
  * Adapted from
- * [jxson/front-matter](https://github.com/jxson/front-matter/blob/36f139ef797bd9e5196a9ede03ef481d7fbca18e/index.js).
+ * {@link https://github.com/jxson/front-matter/blob/36f139ef797bd9e5196a9ede03ef481d7fbca18e/index.js | jxson/front-matter}.
  *
  * Supported formats:
  *

fs/walk.ts

@@ -187,7 +187,7 @@ export async function* walk(
   }
 }
 
-/** Same as walk() but uses synchronous ops */
+/** Same as {@linkcode walk} but uses synchronous ops */
 export function* walkSync(
   root: string | URL,
   {

http/cookie.ts

@@ -388,8 +388,6 @@ function parseSetCookie(value: string): Cookie | null {
  * @return List of cookies
  */
 export function getSetCookies(headers: Headers): Cookie[] {
-  // TODO(lino-levan): remove this ts-ignore when Typescript 5.2 lands in Deno
-  // @ts-ignore Typescript's TS Dom types will be out of date until 5.2
   return headers.getSetCookie()
     /** Parse each `set-cookie` header separately */
     .map(parseSetCookie)

http/mod.ts

@@ -32,7 +32,7 @@
  *
  * > Note: some libraries include accept charset functionality by analyzing the
  * > `Accept-Charset` header. This is a legacy header that
- * > [clients omit and servers should ignore](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Charset)
+ * > {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Charset | clients omit and servers should ignore}
  * > therefore is not provided.
  *
  * ## Cookie maps

ini/mod.ts

@@ -1,8 +1,8 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 /**
  * {@linkcode parse} and {@linkcode stringify} for handling
- * [INI](https://en.wikipedia.org/wiki/INI_file) encoded data, such as the
- * [Desktop Entry specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s03.html).
+ * {@link https://en.wikipedia.org/wiki/INI_file | INI} encoded data, such as the
+ * {@link https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s03.html | Desktop Entry specification}.
  * Values are parsed as strings by default to preserve data parity from the original.
  * Customization is possible in the form of reviver/replacer functions like those in `JSON.parse` and `JSON.stringify`.
  * Nested sections, repeated key names within a section, and key/value arrays are not supported,

io/buffer.ts

@@ -25,7 +25,7 @@ const MAX_SIZE = 2 ** 32 - 2;
  * ArrayBuffer is a fixed memory allocation. Buffer is implemented on top of
  * ArrayBuffer.
  *
- * Based on [Go Buffer](https://golang.org/pkg/bytes/#Buffer).
+ * Based on {@link https://golang.org/pkg/bytes/#Buffer | Go Buffer}.
  */
 
 export class Buffer implements Writer, WriterSync, Reader, ReaderSync {
@@ -179,7 +179,7 @@ export class Buffer implements Writer, WriterSync, Reader, ReaderSync {
    * throw. If the buffer can't grow it will throw an error.
    *
    * Based on Go Lang's
-   * [Buffer.Grow](https://golang.org/pkg/bytes/#Buffer.Grow). */
+   * {@link https://golang.org/pkg/bytes/#Buffer.Grow | Buffer.Grow}. */
   grow(n: number) {
     if (n < 0) {
       throw Error("Buffer.grow: negative count");
@@ -193,7 +193,7 @@ export class Buffer implements Writer, WriterSync, Reader, ReaderSync {
    * If the buffer becomes too large, `.readFrom()` will reject with an error.
    *
    * Based on Go Lang's
-   * [Buffer.ReadFrom](https://golang.org/pkg/bytes/#Buffer.ReadFrom). */
+   * {@link https://golang.org/pkg/bytes/#Buffer.ReadFrom | Buffer.ReadFrom}. */
   async readFrom(r: Reader): Promise<number> {
     let n = 0;
     const tmp = new Uint8Array(MIN_READ);
@@ -223,7 +223,7 @@ export class Buffer implements Writer, WriterSync, Reader, ReaderSync {
    * buffer becomes too large, `.readFromSync()` will throw an error.
    *
    * Based on Go Lang's
-   * [Buffer.ReadFrom](https://golang.org/pkg/bytes/#Buffer.ReadFrom). */
+   * {@link https://golang.org/pkg/bytes/#Buffer.ReadFrom | Buffer.ReadFrom}. */
   readFromSync(r: ReaderSync): number {
     let n = 0;
     const tmp = new Uint8Array(MIN_READ);

json/json_parse_stream.ts

@@ -12,7 +12,7 @@ function isBrankString(str: string) {
 /**
  * Parse each chunk as JSON.
  *
- * This can be used to parse [JSON lines](https://jsonlines.org/), [NDJSON](http://ndjson.org/) and [JSON Text Sequences](https://datatracker.ietf.org/doc/html/rfc7464).
+ * This can be used to parse {@link https://jsonlines.org/ | JSON lines}, {@link http://ndjson.org/ | NDJSON} and {@link https://datatracker.ietf.org/doc/html/rfc7464 | JSON Text Sequences}.
  * Chunks consisting of spaces, tab characters, or newline characters will be ignored.
  *
  * @example

json/json_stringify_stream.ts

@@ -32,12 +32,12 @@ export interface StringifyStreamOptions {
 /**
  * Convert each chunk to JSON string.
  *
- * This can be used to stringify {@link https://jsonlines.org/|JSON lines},
- * {@link https://ndjson.org/|NDJSON},
- * {@link https://datatracker.ietf.org/doc/html/rfc7464|JSON Text Sequences},
- * and {@link https://en.wikipedia.org/wiki/JSON_streaming#Concatenated_JSON|Concatenated JSON}.
+ * This can be used to stringify {@link https://jsonlines.org/ | JSON lines},
+ * {@link https://ndjson.org/ | NDJSON},
+ * {@link https://datatracker.ietf.org/doc/html/rfc7464 | JSON Text Sequences},
+ * and {@link https://en.wikipedia.org/wiki/JSON_streaming#Concatenated_JSON | Concatenated JSON}.
  *
- * You can optionally specify a prefix and suffix for each chunk. The default prefix is "" and the default suffix is "\n".
+ * You can optionally specify a prefix and suffix for each chunk. The default prefix is `""` and the default suffix is `"\n"`.
  *
  * @example
  * ```ts

media_types/mod.ts

@@ -3,13 +3,13 @@
 
 /** Utility functions for media types (MIME types).
  *
- * This API is inspired by the GoLang [`mime`](https://pkg.go.dev/mime) package
- * and [jshttp/mime-types](https://github.com/jshttp/mime-types), and is
+ * This API is inspired by the GoLang {@linkcode https://pkg.go.dev/mime | mime} package
+ * and {@link https://github.com/jshttp/mime-types | jshttp/mime-types}, and is
  * designed to integrate and improve the APIs from
- * [deno.land/x/media_types](https://deno.land/x/media_types).
+ * {@link https://deno.land/x/media_types | x/media_types}.
  *
  * The `vendor` folder contains copy of the
- * [jshttp/mime-db](https://github.com/jshttp/mime-types) `db.json` file along
+ * {@link https://github.com/jshttp/mime-types | jshttp/mime-db} `db.json` file along
  * with its license.
  *
  * @module

semver/mod.ts

@@ -5,7 +5,7 @@
 /**
  * The semantic version parser.
  *
- * Adapted directly from [semver](https://github.com/npm/node-semver).
+ * Adapted directly from {@link https://github.com/npm/node-semver | semver}.
  *
  * ## Versions
  *

streams/buffer.ts

@@ -20,7 +20,7 @@ const DEFAULT_CHUNK_SIZE = 16_640;
  * ArrayBuffer is a fixed memory allocation. Buffer is implemented on top of
  * ArrayBuffer.
  *
- * Based on [Go Buffer](https://golang.org/pkg/bytes/#Buffer). */
+ * Based on {@link https://golang.org/pkg/bytes/#Buffer | Go Buffer}. */
 export class Buffer {
   #buf: Uint8Array; // contents are the bytes buf[off : len(buf)]
   #off = 0; // read at buf[off], write at buf[buf.byteLength]
@@ -167,7 +167,7 @@ export class Buffer {
    * throw. If the buffer can't grow it will throw an error.
    *
    * Based on Go Lang's
-   * [Buffer.Grow](https://golang.org/pkg/bytes/#Buffer.Grow). */
+   * {@link https://golang.org/pkg/bytes/#Buffer.Grow | Buffer.Grow}. */
   grow(n: number) {
     if (n < 0) {
       throw Error("Buffer.grow: negative count");

streams/mod.ts

@@ -1,7 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 /**
  * Utilities for working with the
- * [Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API).
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Streams_API | Streams API}.
  *
  * Includes buffering and conversion.
  *

testing/bdd.ts

@@ -1,6 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
-/** A [BDD](https://en.wikipedia.org/wiki/Behavior-driven_development) interface
+/**
+ * A {@link https://en.wikipedia.org/wiki/Behavior-driven_development | BDD} interface
  * to `Deno.test()` API.
  *
  * With the `bdd.ts` module you can write your tests in a familiar format for