diff --git a/cli/parse_args.ts b/cli/parse_args.ts index 0063a3d85fbd..094678906389 100644 --- a/cli/parse_args.ts +++ b/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 diff --git a/crypto/mod.ts b/crypto/mod.ts index 044778edc922..2505ccb35543 100644 --- a/crypto/mod.ts +++ b/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. * diff --git a/crypto/timing_safe_equal.ts b/crypto/timing_safe_equal.ts index 151bd4f0a8d2..854e84b71bed 100644 --- a/crypto/timing_safe_equal.ts +++ b/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 diff --git a/crypto/unstable_keystack.ts b/crypto/unstable_keystack.ts index c30d577bc095..decbf7c99674 100644 --- a/crypto/unstable_keystack.ts +++ b/crypto/unstable_keystack.ts @@ -46,7 +46,8 @@ function sign(data: Data, key: CryptoKey): Promise { 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 { 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 { 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 { 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 { for (let i = 0; i < this.#keys.length; i++) { const cryptoKey = await this.#toCryptoKey(this.#keys[i]); diff --git a/csv/stringify.ts b/csv/stringify.ts index 0e19d1117655..310e474f5082 100644 --- a/csv/stringify.ts +++ b/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. * diff --git a/dotenv/mod.ts b/dotenv/mod.ts index b9a3d83df688..fd49e594c970 100644 --- a/dotenv/mod.ts +++ b/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 " }`) diff --git a/expect/mod.ts b/expect/mod.ts index 066fee81a154..b79709940a6f 100644 --- a/expect/mod.ts +++ b/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"; diff --git a/flags/mod.ts b/flags/mod.ts index 33402e8dee2f..da7e069ea38f 100644 --- a/flags/mod.ts +++ b/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 diff --git a/front_matter/mod.ts b/front_matter/mod.ts index 84077e5ff22c..9e5585d8f5e9 100644 --- a/front_matter/mod.ts +++ b/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: * diff --git a/fs/walk.ts b/fs/walk.ts index ff075b80ccd2..80c6e3a069a1 100644 --- a/fs/walk.ts +++ b/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, { diff --git a/http/cookie.ts b/http/cookie.ts index 443322ee4ce8..0345dad8843a 100644 --- a/http/cookie.ts +++ b/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) diff --git a/http/mod.ts b/http/mod.ts index 7311a15d0f9c..4c23569517e4 100644 --- a/http/mod.ts +++ b/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 diff --git a/ini/mod.ts b/ini/mod.ts index 27561d40afef..81e68be65dd9 100644 --- a/ini/mod.ts +++ b/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, diff --git a/io/buffer.ts b/io/buffer.ts index db9344074928..46c9555fc576 100644 --- a/io/buffer.ts +++ b/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 { 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); diff --git a/json/json_parse_stream.ts b/json/json_parse_stream.ts index ed7455ab57c8..b52e0c458d26 100644 --- a/json/json_parse_stream.ts +++ b/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 diff --git a/json/json_stringify_stream.ts b/json/json_stringify_stream.ts index fe1062b88acc..16da93685a29 100644 --- a/json/json_stringify_stream.ts +++ b/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 diff --git a/media_types/mod.ts b/media_types/mod.ts index ec8196808ce8..f6d509f81edd 100644 --- a/media_types/mod.ts +++ b/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 diff --git a/semver/mod.ts b/semver/mod.ts index a239748f14bb..48429c13df74 100644 --- a/semver/mod.ts +++ b/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 * diff --git a/streams/buffer.ts b/streams/buffer.ts index 6b0dd0709240..ba3f24222624 100644 --- a/streams/buffer.ts +++ b/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"); diff --git a/streams/mod.ts b/streams/mod.ts index 34f6b61a53a1..05010eedbf69 100644 --- a/streams/mod.ts +++ b/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. * diff --git a/testing/bdd.ts b/testing/bdd.ts index 86b3e0182853..26ab5bdc93ce 100644 --- a/testing/bdd.ts +++ b/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 diff --git a/toml/mod.ts b/toml/mod.ts index 3c6d18a345e1..500f57884845 100644 --- a/toml/mod.ts +++ b/toml/mod.ts @@ -3,36 +3,34 @@ /** * {@linkcode parse} and {@linkcode stringify} for handling - * [TOML](https://toml.io/en/latest) encoded data. Be sure to read the supported + * {@link https://toml.io/en/latest | TOML} encoded data. Be sure to read the supported * types as not every spec is supported at the moment and the handling in * TypeScript side is a bit different. * * ## Supported types and handling * - * - :heavy_check_mark: [Keys](https://toml.io/en/latest#keys) - * - :exclamation: [String](https://toml.io/en/latest#string) - * - :heavy_check_mark: [Multiline String](https://toml.io/en/latest#string) - * - :heavy_check_mark: [Literal String](https://toml.io/en/latest#string) - * - :exclamation: [Integer](https://toml.io/en/latest#integer) - * - :heavy_check_mark: [Float](https://toml.io/en/latest#float) - * - :heavy_check_mark: [Boolean](https://toml.io/en/latest#boolean) - * - :heavy_check_mark: - * [Offset Date-time](https://toml.io/en/latest#offset-date-time) - * - :heavy_check_mark: - * [Local Date-time](https://toml.io/en/latest#local-date-time) - * - :heavy_check_mark: [Local Date](https://toml.io/en/latest#local-date) - * - :exclamation: [Local Time](https://toml.io/en/latest#local-time) - * - :heavy_check_mark: [Table](https://toml.io/en/latest#table) - * - :heavy_check_mark: [Inline Table](https://toml.io/en/latest#inline-table) - * - :exclamation: [Array of Tables](https://toml.io/en/latest#array-of-tables) - * - * :exclamation: _Supported with warnings see [Warning](#Warning)._ - * - * ### :warning: Warning + * - [x] [Keys](https://toml.io/en/latest#keys) + * - [ ] [String](https://toml.io/en/latest#string) + * - [x] [Multiline String](https://toml.io/en/latest#string) + * - [x] [Literal String](https://toml.io/en/latest#string) + * - [ ] [Integer](https://toml.io/en/latest#integer) + * - [x] [Float](https://toml.io/en/latest#float) + * - [x] [Boolean](https://toml.io/en/latest#boolean) + * - [x] [Offset Date-time](https://toml.io/en/latest#offset-date-time) + * - [x] [Local Date-time](https://toml.io/en/latest#local-date-time) + * - [x] [Local Date](https://toml.io/en/latest#local-date) + * - [ ] [Local Time](https://toml.io/en/latest#local-time) + * - [x] [Table](https://toml.io/en/latest#table) + * - [x] [Inline Table](https://toml.io/en/latest#inline-table) + * - [ ] [Array of Tables](https://toml.io/en/latest#array-of-tables) + * + * _Supported with warnings see [Warning](#Warning)._ + * + * ### Warning * * #### String * - * - Regex : Due to the spec, there is no flag to detect regex properly in a TOML + * - Regex: Due to the spec, there is no flag to detect regex properly in a TOML * declaration. So the regex is stored as string. * * #### Integer diff --git a/yaml/mod.ts b/yaml/mod.ts index 4574cb332b6b..a47c4473adc3 100644 --- a/yaml/mod.ts +++ b/yaml/mod.ts @@ -4,10 +4,10 @@ /** * {@linkcode parse} and {@linkcode stringify} for handling - * [YAML](https://yaml.org/) encoded data. + * {@link https://yaml.org/ | YAML} encoded data. * * Ported from - * [js-yaml v3.13.1](https://github.com/nodeca/js-yaml/commit/665aadda42349dcae869f12040d9b10ef18d12da) + * {@link https://github.com/nodeca/js-yaml/commit/665aadda42349dcae869f12040d9b10ef18d12da | js-yaml v3.13.1}. * * If your YAML contains multiple documents in it, you can use {@linkcode parseAll} for * handling it.