docs(archive,assert,cache,cli,encoding,html,http,net,streams,text): remove unstable Markdown alert (#5672)

* docs(archive,cli,html,http,net,streams,text): remove unstable Markdown alert * update * fix * update * fmt * fix
2024-11-21 12:40:03 +00:00 · 2024-08-22 16:55:17 +10:00 · 2024-08-22 16:55:17 +10:00 · dea7d7701a
commit dea7d7701a
parent afb9a4f336
20 changed files with 47 additions and 143 deletions
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@ -174,18 +174,14 @@ So concrete examples are:
 ### Notices for unstable APIs

 Each unstable API must have the
-[`@experimental`](https://tsdoc.org/pages/tags/experimental/) TSDoc tag and a
-[warning alert](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
-after the starting description.
+[`@experimental`](https://tsdoc.org/pages/tags/experimental/) TSDoc tag after
+the starting description.

 ```ts
 /**
 * <description>
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * ...
 */
--- a/archive/_common.ts
+++ b/archive/_common.ts
@ -6,10 +6,7 @@ import type { Reader } from "@std/io/types";
 /**
 * Base interface for {@linkcode TarMeta}.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export interface TarInfo {
  /**
@ -47,10 +44,7 @@ export interface TarInfo {
 /**
 * Base interface for {@linkcode TarMetaWithLinkName}.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export interface TarMeta extends TarInfo {
  /**
--- a/archive/mod.ts
+++ b/archive/mod.ts
@ -32,7 +32,7 @@
 /**
 * Tar is a utility for collecting multiple files (or any arbitrary data) into one
 * archive file, while untar is the inverse utility to extract the files from an
- * archive.  Files are not compressed, only collected into the archive.
+ * archive. Files are not compressed, only collected into the archive.
 *
 * ```ts no-eval
 * import { Tar } from "@std/archive/tar";
@ -62,10 +62,7 @@
 * writer.close();
 * ```
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @module
 */
--- a/archive/tar.ts
+++ b/archive/tar.ts
@ -44,10 +44,7 @@ export type { TarInfo, TarMeta };
 /**
 * Options for {@linkcode Tar.append}.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export interface TarOptions extends TarInfo {
  /**
@ -125,10 +122,7 @@ function formatHeader(data: TarData): Uint8Array {
 /**
 * Base interface for {@linkcode TarDataWithSource}.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export interface TarData {
  /** Name of the file, excluding directory names (if any). */
@ -179,10 +173,7 @@ export interface TarData {
 /**
 * Tar data interface for {@linkcode Tar.data}.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export interface TarDataWithSource extends TarData {
  /**
@ -250,10 +241,7 @@ export interface TarDataWithSource extends TarData {
 * writer.close();
 * ```
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export class Tar {
  /** Tar data. */
--- a/archive/untar.ts
+++ b/archive/untar.ts
@ -46,10 +46,7 @@ export type { Reader };
 * Extend TarMeta with the `linkName` property so that readers can access
 * symbolic link values without polluting the world of archive writers.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export interface TarMetaWithLinkName extends TarMeta {
  /** File name of the symbolic link. */
@ -59,10 +56,7 @@ export interface TarMetaWithLinkName extends TarMeta {
 /**
 * Tar header with raw, unprocessed bytes as values.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export type TarHeader = {
  [key in UstarFields]: Uint8Array;
@ -102,10 +96,7 @@ function parseHeader(buffer: Uint8Array): TarHeader {
 /**
 * Tar entry
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @example Usage
 * ```ts no-assert
@ -133,10 +124,7 @@ export interface TarEntry extends TarMetaWithLinkName {}
 /**
 * Contains tar header metadata and a reader to the entry's body.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @example Usage
 * ```ts no-assert
@ -377,10 +365,7 @@ export class TarEntry implements Reader {
 * }
 * ```
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export class Untar {
  /** Internal reader. */
--- a/assert/never.ts
+++ b/assert/never.ts
@ -27,12 +27,10 @@ import { AssertionError } from "./assertion_error.ts";
 */

 /**
- * **UNSTABLE**: New API, yet to be vetted.
- *
 * Make an assertion that `x` is of type `never`.
 * If not then throw.
 *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @example Exhaustivenss check
 * ```ts
--- a/cache/lru_cache.ts
+++ b/cache/lru_cache.ts
@ -7,7 +7,7 @@ export type { MemoizationCache };
 * 	https://en.wikipedia.org/wiki/Cache_replacement_policies#LRU
 * ) cache.
 *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * Automatically removes entries above the max size based on when they were
 * last accessed with `get`, `set`, or `has`.
--- a/cache/memoize.ts
+++ b/cache/memoize.ts
@ -7,7 +7,7 @@ import { _serializeArgList } from "./_serialize_arg_list.ts";
 /**
 * A cache suitable for use with {@linkcode memoize}.
 *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export type MemoizationCache<K, V> = {
  has: (key: K) => boolean;
@ -19,7 +19,7 @@ export type MemoizationCache<K, V> = {
 /**
 * Options for {@linkcode memoize}.
 *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @typeParam Fn The type of the function to memoize.
 * @typeParam Key The type of the cache key.
@ -64,7 +64,7 @@ export type MemoizeOptions<
 /**
 * Cache the results of a function based on its arguments.
 *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @typeParam Fn The type of the function to memoize.
 * @typeParam Key The type of the cache key.
--- a/cli/spinner.ts
+++ b/cli/spinner.ts
@ -21,10 +21,7 @@ export type Ansi = string & {};
 /**
 * Color options for {@linkcode SpinnerOptions.color}.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export type Color =
  | "black"
@ -53,10 +50,7 @@ const COLORS: Record<Color, string> = {
 /**
 * Options for {@linkcode Spinner}.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export interface SpinnerOptions {
  /**
@ -86,8 +80,7 @@ export interface SpinnerOptions {
 /**
 * A spinner that can be used to indicate that something is loading.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @example Usage
 * ```ts no-eval
@ -101,8 +94,6 @@ export interface SpinnerOptions {
 *  console.log("Finished loading!");
 * }, 3_000);
 * ```
- *
- * @experimental
 */
 export class Spinner {
  #spinner: string[];
--- a/encoding/base32hex.ts
+++ b/encoding/base32hex.ts
@ -7,6 +7,8 @@
 * {@link https://www.rfc-editor.org/rfc/rfc4648.html#section-7 | base32hex}
 * encoding and decoding.
 *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
 * Modified from {@link [base32]}.
 *
 * This module is browser compatible.
@ -23,8 +25,6 @@
 * );
 * ```
 *
- * @experimental
- *
 * @module
 */
 import { decode, encode } from "./_base32_common.ts";
@ -36,6 +36,8 @@ lookup.forEach((c, i) => revLookup[c.charCodeAt(0)] = i);
 /**
 * Decodes a base32hex-encoded string.
 *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
 * @see {@link https://www.rfc-editor.org/rfc/rfc4648.html#section-7}
 *
 * @param b32 The base32hex-encoded string to decode.
@ -51,8 +53,6 @@ lookup.forEach((c, i) => revLookup[c.charCodeAt(0)] = i);
 *   new TextEncoder().encode("6c60c0"),
 * );
 * ```
- *
- * @experimental
 */
 export function decodeBase32Hex(b32: string): Uint8Array {
  return decode(b32, lookup);
@ -61,6 +61,8 @@ export function decodeBase32Hex(b32: string): Uint8Array {
 /**
 * Converts data into a base32hex-encoded string.
 *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
 * @see {@link https://www.rfc-editor.org/rfc/rfc4648.html#section-7}
 *
 * @param data The data to encode.
@ -73,8 +75,6 @@ export function decodeBase32Hex(b32: string): Uint8Array {
 *
 * assertEquals(encodeBase32Hex("6c60c0"), "6PHJCC3360======");
 * ```
- *
- * @experimental
 */
 export function encodeBase32Hex(
  data: ArrayBuffer | Uint8Array | string,
--- a/html/is_valid_custom_element_name.ts
+++ b/html/is_valid_custom_element_name.ts
@ -20,10 +20,7 @@ const CUSTOM_ELEMENT_NAME_CHARS =
 * requirements defined in
 * {@link https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name}.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * The element name must not be any of the following:
 * - `annotation-xml`
--- a/http/header.ts
+++ b/http/header.ts
@ -5,10 +5,7 @@
 /**
 * HTTP Headers with status permanent
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @see {@link https://www.iana.org/assignments/http-fields/http-fields.xhtml#field-names | IANA Hypertext Transfer Protocol (HTTP) Field Name Registry}
 */
@ -1198,9 +1195,6 @@ export const HEADER = {
 /**
 * A HTTP Header
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export type Header = typeof HEADER[keyof typeof HEADER];
--- a/http/method.ts
+++ b/http/method.ts
@ -5,10 +5,7 @@
 /**
 * HTTP Methods derived from IANA Hypertext Transfer Protocol (HTTP) Method Registry
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @see {@link https://www.iana.org/assignments/http-methods/http-methods.xhtml#methods | IANA Hypertext Transfer Protocol (HTTP) Method Registry}
 */
@ -296,9 +293,6 @@ export const METHOD = {
 /**
 * A HTTP Method
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export type Method = typeof METHOD[keyof typeof METHOD];
--- a/http/route.ts
+++ b/http/route.ts
@ -3,10 +3,7 @@
 /**
 * Request handler for {@linkcode Route}.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * Extends {@linkcode Deno.ServeHandlerInfo} by adding adding a `params` argument.
 *
@ -23,10 +20,7 @@ export type Handler = (
 /**
 * Route configuration for {@linkcode route}.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 */
 export interface Route {
  /**
@ -48,10 +42,7 @@ export interface Route {
 /**
 * Routes requests to different handlers based on the request path and method.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @example Usage
 * ```ts no-eval
--- a/http/signed_cookie.ts
+++ b/http/signed_cookie.ts
@ -15,10 +15,7 @@ function splitByLast(value: string, separator: string): [string, string] {
 * Returns a promise with the signed cookie value from the given cryptographic
 * key.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @example Usage
 * ```ts no-eval no-assert
@ -58,10 +55,7 @@ export async function signCookie(
 /**
 * Returns a promise of a boolean indicating whether the signed cookie is valid.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @example Usage
 * ```ts no-eval no-assert
@ -102,12 +96,9 @@ export async function verifySignedCookie(
 /**
 * Parses a signed cookie to get its value.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
 * Important: always verify the cookie using {@linkcode verifySignedCookie} first.
 *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @example Usage
 * ```ts no-eval no-assert
--- a/net/get_network_address.ts
+++ b/net/get_network_address.ts
@ -2,8 +2,8 @@
 /**
 * Gets the IPv4 or IPv6 network address of the machine.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+
 *
 * This is inspired by the util of the same name in
 * {@linkcode https://www.npmjs.com/package/serve | npm:serve}.
@ -32,8 +32,6 @@
 *
 * Deno.serve({ port: 0, hostname }, () => new Response("Hello, world!"));
 * ```
- *
- * @experimental
 */
 export function getNetworkAddress(
  family: Deno.NetworkInterfaceInfo["family"] = "IPv4",
--- a/streams/fixed_chunk_stream.ts
+++ b/streams/fixed_chunk_stream.ts
@ -4,10 +4,7 @@
 * A transform stream that resize {@linkcode Uint8Array} chunks into perfectly
 * `size` chunks with the exception of the last chunk.
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @example Usage
 * ```ts
--- a/streams/to_lines.ts
+++ b/streams/to_lines.ts
@ -6,6 +6,8 @@ import { TextLineStream } from "./text_line_stream.ts";
 * Converts a {@linkcode ReadableStream} of {@linkcode Uint8Array}s into one of
 * lines delimited by `\n` or `\r\n`. Trims the last line if empty.
 *
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
+ *
 * @param readable A stream of {@linkcode Uint8Array}s.
 * @param options Stream options.
 * @returns A stream of lines delimited by `\n` or `\r\n`.
@ -28,8 +30,6 @@ import { TextLineStream } from "./text_line_stream.ts";
 *   "apoiuzt\rqwr\r09ei\rqwrjiowqr\r",
 * ]);
 * ```
- *
- * @experimental
 */
 export function toLines(
  readable: ReadableStream<Uint8Array>,
--- a/text/slugify.ts
+++ b/text/slugify.ts
@ -16,8 +16,6 @@
 *
 * @param input The string that is going to be converted into a slug
 * @returns The string as a slug
- *
- * @experimental
 */
 export function slugify(input: string): string {
  return input
--- a/text/to_constant_case.ts
+++ b/text/to_constant_case.ts
@ -6,10 +6,7 @@ import { splitToWords } from "./_util.ts";
 /**
 * Converts a string into CONSTANT_CASE (also known as SCREAMING_SNAKE_CASE).
 *
- * > [!WARNING]
- * > **UNSTABLE**: New API, yet to be vetted.
- *
- * @experimental
+ * @experimental **UNSTABLE**: New API, yet to be vetted.
 *
 * @example Usage
 * ```ts
@ -21,8 +18,6 @@ import { splitToWords } from "./_util.ts";
 *
 * @param input The string that is going to be converted into CONSTANT_CASE
 * @returns The string as CONSTANT_CASE
- *
- * @experimental
 */
 export function toConstantCase(input: string): string {
  input = input.trim();