chore: improve built-in API documentation (#16158)

Co-authored-by: crowlkats <crowlkats@toaxl.com>
Co-authored-by: Colin Ihrig <cjihrig@gmail.com>
Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>

1 files changed, 638 insertions, 214 deletions

diff --git a/cli/dts/lib.deno.unstable.d.ts b/cli/dts/lib.deno.unstable.d.ts
index ba6d03c7e..cde76d4d8 100644
--- a/cli/dts/lib.deno.unstable.d.ts
+++ b/cli/dts/lib.deno.unstable.d.ts
@@ -8,28 +8,38 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * The interface for defining a benchmark test using {@linkcode Deno.bench}.
+   *
    * @category Testing
    */
   export interface BenchDefinition {
+    /** The test function which will be benchmarked. */
     fn: () => void | Promise<void>;
+    /** The name of the test, which will be used in displaying the results. */
     name: string;
+    /** If truthy, the benchmark test will be ignored/skipped. */
     ignore?: boolean;
     /** Group name for the benchmark.
-     * Grouped benchmarks produce a time summary */
+     *
+     * Grouped benchmarks produce a group time summary, where the difference
+     * in performance between each test of the group is compared. */
     group?: string;
-    /** Benchmark should be used as the baseline for other benchmarks
-     * If there are multiple baselines in a group, the first one is used as the baseline */
+    /** Benchmark should be used as the baseline for other benchmarks.
+     *
+     * If there are multiple baselines in a group, the first one is used as the
+     * baseline. */
     baseline?: boolean;
     /** If at least one bench has `only` set to true, only run benches that have
-     * `only` set to true and fail the bench suite. */
+     * `only` set to `true` and fail the bench suite. */
     only?: boolean;
     /** Ensure the bench case does not prematurely cause the process to exit,
-     * for example via a call to `Deno.exit`. Defaults to true. */
+     * for example via a call to {@linkcode Deno.exit}. Defaults to `true`. */
     sanitizeExit?: boolean;
-
     /** Specifies the permissions that should be used to run the bench.
-     * Set this to "inherit" to keep the calling thread's permissions.
-     * Set this to "none" to revoke all permissions.
+     *
+     * Set this to `"inherit"` to keep the calling thread's permissions.
+     *
+     * Set this to `"none"` to revoke all permissions.
      *
      * Defaults to "inherit".
      */
@@ -38,15 +48,18 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Register a bench which will be run when `deno bench` is used on the command
-   * line and the containing module looks like a bench module.
-   * `fn` can be async if required.
+   * Register a benchmark test which will be run when `deno bench` is used on
+   * the command line and the containing module looks like a bench module.
+   *
+   * If the test function (`fn`) returns a promise or is async, the test runner
+   * will await resolution to consider the test complete.
+   *
    * ```ts
-   * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts";
+   * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
    *
    * Deno.bench({
    *   name: "example test",
-   *   fn(): void {
+   *   fn() {
    *     assertEquals("world", "world");
    *   },
    * });
@@ -54,7 +67,7 @@ declare namespace Deno {
    * Deno.bench({
    *   name: "example ignored test",
    *   ignore: Deno.build.os === "windows",
-   *   fn(): void {
+   *   fn() {
    *     // This test is ignored only on Windows machines
    *   },
    * });
@@ -75,18 +88,20 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Register a bench which will be run when `deno bench` is used on the command
-   * line and the containing module looks like a bench module.
-   * `fn` can be async if required.
+   * Register a benchmark test which will be run when `deno bench` is used on
+   * the command line and the containing module looks like a bench module.
+   *
+   * If the test function (`fn`) returns a promise or is async, the test runner
+   * will await resolution to consider the test complete.
    *
    * ```ts
-   * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts";
+   * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
    *
-   * Deno.bench("My test description", (): void => {
+   * Deno.bench("My test description", () => {
    *   assertEquals("hello", "hello");
    * });
    *
-   * Deno.bench("My async test description", async (): Promise<void> => {
+   * Deno.bench("My async test description", async () => {
    *   const decoder = new TextDecoder("utf-8");
    *   const data = await Deno.readFile("hello_world.txt");
    *   assertEquals(decoder.decode(data), "Hello world");
@@ -102,18 +117,20 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Register a bench which will be run when `deno bench` is used on the command
-   * line and the containing module looks like a bench module.
-   * `fn` can be async if required. Declared function must have a name.
+   * Register a benchmark test which will be run when `deno bench` is used on
+   * the command line and the containing module looks like a bench module.
+   *
+   * If the test function (`fn`) returns a promise or is async, the test runner
+   * will await resolution to consider the test complete.
    *
    * ```ts
-   * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts";
+   * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
    *
-   * Deno.bench(function myTestName(): void {
+   * Deno.bench(function myTestName() {
    *   assertEquals("hello", "hello");
    * });
    *
-   * Deno.bench(async function myOtherTestName(): Promise<void> {
+   * Deno.bench(async function myOtherTestName() {
    *   const decoder = new TextDecoder("utf-8");
    *   const data = await Deno.readFile("hello_world.txt");
    *   assertEquals(decoder.decode(data), "Hello world");
@@ -126,22 +143,32 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Register a bench which will be run when `deno bench` is used on the command
-   * line and the containing module looks like a bench module.
-   * `fn` can be async if required.
+   * Register a benchmark test which will be run when `deno bench` is used on
+   * the command line and the containing module looks like a bench module.
+   *
+   * If the test function (`fn`) returns a promise or is async, the test runner
+   * will await resolution to consider the test complete.
    *
    * ```ts
-   * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts";
+   * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
    *
-   * Deno.bench("My test description", { permissions: { read: true } }, (): void => {
-   *   assertEquals("hello", "hello");
-   * });
+   * Deno.bench(
+   *   "My test description",
+   *   { permissions: { read: true } },
+   *   () => {
+   *    assertEquals("hello", "hello");
+   *   }
+   * );
    *
-   * Deno.bench("My async test description", { permissions: { read: false } }, async (): Promise<void> => {
-   *   const decoder = new TextDecoder("utf-8");
-   *   const data = await Deno.readFile("hello_world.txt");
-   *   assertEquals(decoder.decode(data), "Hello world");
-   * });
+   * Deno.bench(
+   *   "My async test description",
+   *   { permissions: { read: false } },
+   *   async () => {
+   *     const decoder = new TextDecoder("utf-8");
+   *     const data = await Deno.readFile("hello_world.txt");
+   *     assertEquals(decoder.decode(data), "Hello world");
+   *   }
+   * );
    * ```
    *
    * @category Testing
@@ -154,22 +181,30 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Register a bench which will be run when `deno bench` is used on the command
-   * line and the containing module looks like a bench module.
-   * `fn` can be async if required.
+   * Register a benchmark test which will be run when `deno bench` is used on
+   * the command line and the containing module looks like a bench module.
+   *
+   * If the test function (`fn`) returns a promise or is async, the test runner
+   * will await resolution to consider the test complete.
    *
    * ```ts
-   * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts";
+   * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
    *
-   * Deno.bench({ name: "My test description", permissions: { read: true } }, (): void => {
-   *   assertEquals("hello", "hello");
-   * });
+   * Deno.bench(
+   *   { name: "My test description", permissions: { read: true } },
+   *   () => {
+   *     assertEquals("hello", "hello");
+   *   }
+   * );
    *
-   * Deno.bench({ name: "My async test description", permissions: { read: false } }, async (): Promise<void> => {
-   *   const decoder = new TextDecoder("utf-8");
-   *   const data = await Deno.readFile("hello_world.txt");
-   *   assertEquals(decoder.decode(data), "Hello world");
-   * });
+   * Deno.bench(
+   *   { name: "My async test description", permissions: { read: false } },
+   *   async () => {
+   *     const decoder = new TextDecoder("utf-8");
+   *     const data = await Deno.readFile("hello_world.txt");
+   *     assertEquals(decoder.decode(data), "Hello world");
+   *   }
+   * );
    * ```
    *
    * @category Testing
@@ -181,22 +216,30 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Register a bench which will be run when `deno bench` is used on the command
-   * line and the containing module looks like a bench module.
-   * `fn` can be async if required. Declared function must have a name.
+   * Register a benchmark test which will be run when `deno bench` is used on
+   * the command line and the containing module looks like a bench module.
+   *
+   * If the test function (`fn`) returns a promise or is async, the test runner
+   * will await resolution to consider the test complete.
    *
    * ```ts
-   * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts";
+   * import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
    *
-   * Deno.bench({ permissions: { read: true } }, function myTestName(): void {
-   *   assertEquals("hello", "hello");
-   * });
+   * Deno.bench(
+   *   { permissions: { read: true } },
+   *   function myTestName() {
+   *     assertEquals("hello", "hello");
+   *   }
+   * );
    *
-   * Deno.bench({ permissions: { read: false } }, async function myOtherTestName(): Promise<void> {
-   *   const decoder = new TextDecoder("utf-8");
-   *   const data = await Deno.readFile("hello_world.txt");
-   *   assertEquals(decoder.decode(data), "Hello world");
-   * });
+   * Deno.bench(
+   *   { permissions: { read: false } },
+   *   async function myOtherTestName() {
+   *     const decoder = new TextDecoder("utf-8");
+   *     const data = await Deno.readFile("hello_world.txt");
+   *     assertEquals(decoder.decode(data), "Hello world");
+   *   }
+   * );
    * ```
    *
    * @category Testing
@@ -220,7 +263,7 @@ declare namespace Deno {
    * This API is under consideration to determine if permissions are required to
    * call it.
    *
-   * NOTE:  This API is not implemented on Windows
+   * *Note*: This API is not implemented on Windows
    *
    * @category File System
    */
@@ -246,49 +289,52 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * Information returned from a call to {@linkcode Deno.systemMemoryInfo}.
+   *
    * @category Runtime Environment
    */
   export interface SystemMemoryInfo {
-    /** Total installed memory */
+    /** Total installed memory in bytes. */
     total: number;
-    /** Unused memory */
+    /** Unused memory in bytes. */
     free: number;
-    /** Estimation of how much memory is available  for  starting  new
-     * applications, without  swapping. Unlike the data provided by the cache or
+    /** Estimation of how much memory, in bytes, is available for starting new
+     * applications, without swapping. Unlike the data provided by the cache or
      * free fields, this field takes into account page cache and also that not
-     * all reclaimable memory slabs will be reclaimed due to items being in use
+     * all reclaimable memory will be reclaimed due to items being in use.
      */
     available: number;
-    /** Memory used by kernel buffers */
+    /** Memory used by kernel buffers. */
     buffers: number;
-    /** Memory used by the page cache and slabs */
+    /** Memory used by the page cache and slabs. */
     cached: number;
-    /** Total swap memory */
+    /** Total swap memory. */
     swapTotal: number;
-    /** Unused swap memory */
+    /** Unused swap memory. */
     swapFree: number;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * The information of the network interface.
+   * The information for a network interface returned from a call to
+   * {@linkcode Deno.networkInterfaces}.
    *
    * @category Network
    */
   export interface NetworkInterfaceInfo {
-    /** The network interface name */
+    /** The network interface name. */
     name: string;
-    /** The IP protocol version */
+    /** The IP protocol version. */
     family: "IPv4" | "IPv6";
-    /** The IP address */
+    /** The IP address bound to the interface. */
     address: string;
-    /** The netmask */
+    /** The netmask applied to the interface. */
     netmask: string;
-    /** The IPv6 scope id or null */
+    /** The IPv6 scope id or `null`. */
     scopeid: number | null;
-    /** The CIDR range */
+    /** The CIDR range. */
     cidr: string;
-    /** The MAC address */
+    /** The MAC address. */
     mac: string;
   }
 
@@ -309,7 +355,8 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Returns the user id of the process on POSIX platforms. Returns null on Windows.
+   * Returns the user id of the Deno process on POSIX platforms. Returns `null`
+   * on Windows.
    *
    * ```ts
    * console.log(Deno.getUid());
@@ -324,7 +371,8 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Returns the group id of the process on POSIX platforms. Returns null on windows.
+   * Returns the group id of the process on POSIX platforms. Returns `null` on
+   * Windows.
    *
    * ```ts
    * console.log(Deno.getGid());
@@ -367,37 +415,47 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * The native boolean type for interfacing to foreign functions.
+   *
    * @category FFI
    */
   type NativeBooleanType = "bool";
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * The native pointer type for interfacing to foreign functions.
+   *
    * @category FFI
    */
   type NativePointerType = "pointer";
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * The native buffer type for interfacing to foreign functions.
+   *
    * @category FFI
    */
   type NativeBufferType = "buffer";
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * The native function type for interfacing with foreign functions.
+   *
    * @category FFI
    */
   type NativeFunctionType = "function";
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * The native void type for interfacing with foreign functions.
+   *
    * @category FFI
    */
   type NativeVoidType = "void";
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * All possible types for interfacing with foreign functions.
+   * All supported types for interfacing with foreign functions.
    *
    * @category FFI
    */
@@ -417,6 +475,9 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * A utility type conversion for foreign symbol parameters and unsafe callback
+   * return types.
+   *
    * @category FFI
    */
   type ToNativeTypeMap =
@@ -438,6 +499,8 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * A utility type for conversion for unsafe callback return types.
+   *
    * @category FFI
    */
   type ToNativeResultTypeMap = ToNativeTypeMap & Record<NativeVoidType, void>;
@@ -453,6 +516,8 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * A utility type for conversion of parameter types of foreign functions.
+   *
    * @category FFI
    */
   type ToNativeParameterTypes<T extends readonly NativeType[]> =
@@ -467,6 +532,9 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * A utility type for conversion of foreign symbol return types and unsafe
+   * callback parameters.
+   *
    * @category FFI
    */
   type FromNativeTypeMap =
@@ -488,6 +556,8 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * A utility type for conversion for foreign symbol return types.
+   *
    * @category FFI
    */
   type FromNativeResultTypeMap =
@@ -521,7 +591,8 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * A foreign function as defined by its parameter and result types.
+   * The interface for a foreign function as defined by its parameter and result
+   * types.
    *
    * @category FFI
    */
@@ -530,13 +601,21 @@ declare namespace Deno {
     Result extends NativeResultType = NativeResultType,
     NonBlocking extends boolean = boolean,
   > {
-    /** Name of the symbol, defaults to the key name in symbols object. */
+    /** Name of the symbol.
+     *
+     * Defaults to the key name in symbols object. */
     name?: string;
+    /** The parameters of the foreign function. */
     parameters: Parameters;
+    /** The result (return value) of the foreign function. */
     result: Result;
-    /** When true, function calls will run on a dedicated blocking thread and will return a Promise resolving to the `result`. */
+    /** When `true`, function calls will run on a dedicated blocking thread and
+     * will return a `Promise` resolving to the `result`. */
     nonblocking?: NonBlocking;
-    /** When true, function calls can safely callback into JS or trigger a GC event. Default is `false`. */
+    /** When `true`, function calls can safely callback into JavaScript or
+     * trigger a garbage collection event.
+     *
+     * Default is `false`. */
     callback?: boolean;
   }
 
@@ -547,6 +626,7 @@ declare namespace Deno {
   export interface ForeignStatic<Type extends NativeType = NativeType> {
     /** Name of the symbol, defaults to the key name in symbols object. */
     name?: string;
+    /** The type of the foreign static value. */
     type: Type;
   }
 
@@ -562,7 +642,7 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Infers a foreign symbol.
+   * A utility type that infers a foreign symbol.
    *
    * @category FFI
    */
@@ -597,7 +677,7 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Infers a foreign library interface.
+   * A utility type that infers a foreign library interface.
    *
    * @category FFI
    */
@@ -609,9 +689,9 @@ declare namespace Deno {
    *
    * Pointer type depends on the architecture and actual pointer value.
    *
-   * On a 32 bit system all pointer values are plain numbers. On a 64 bit
-   * system pointer values are represented as numbers if the value is below
-   * `Number.MAX_SAFE_INTEGER`.
+   * On a 32 bit host system all pointer values are plain numbers. On a 64 bit
+   * host system pointer values are represented as numbers if the value is below
+   * `Number.MAX_SAFE_INTEGER`, otherwise they are provided as bigints.
    *
    * @category FFI
    */
@@ -625,18 +705,16 @@ declare namespace Deno {
    * @category FFI
    */
   export class UnsafePointer {
-    /**
-     * Return the direct memory pointer to the typed array in memory
-     */
+    /** Return the direct memory pointer to the typed array in memory. */
     static of(value: Deno.UnsafeCallback | BufferSource): PointerValue;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
    * An unsafe pointer view to a memory location as specified by the `pointer`
-   * value. The `UnsafePointerView` API mimics the standard built in interface
-   * `DataView` for accessing the underlying types at an memory location
-   * (numbers, strings and raw bytes).
+   * value. The `UnsafePointerView` API follows the standard built in interface
+   * {@linkcode DataView} for accessing the underlying types at an memory
+   * location (numbers, strings and raw bytes).
    *
    * @category FFI
    */
@@ -647,41 +725,63 @@ declare namespace Deno {
 
     /** Gets a boolean at the specified byte offset from the pointer. */
     getBool(offset?: number): boolean;
-    /** Gets an unsigned 8-bit integer at the specified byte offset from the pointer. */
+    /** Gets an unsigned 8-bit integer at the specified byte offset from the
+     * pointer. */
     getUint8(offset?: number): number;
-    /** Gets a signed 8-bit integer at the specified byte offset from the pointer. */
+    /** Gets a signed 8-bit integer at the specified byte offset from the
+     * pointer. */
     getInt8(offset?: number): number;
-    /** Gets an unsigned 16-bit integer at the specified byte offset from the pointer. */
+    /** Gets an unsigned 16-bit integer at the specified byte offset from the
+     * pointer. */
     getUint16(offset?: number): number;
-    /** Gets a signed 16-bit integer at the specified byte offset from the pointer. */
+    /** Gets a signed 16-bit integer at the specified byte offset from the
+     * pointer. */
     getInt16(offset?: number): number;
-    /** Gets an unsigned 32-bit integer at the specified byte offset from the pointer. */
+    /** Gets an unsigned 32-bit integer at the specified byte offset from the
+     * pointer. */
     getUint32(offset?: number): number;
-    /** Gets a signed 32-bit integer at the specified byte offset from the pointer. */
+    /** Gets a signed 32-bit integer at the specified byte offset from the
+     * pointer. */
     getInt32(offset?: number): number;
-    /** Gets an unsigned 64-bit integer at the specified byte offset from the pointer. */
+    /** Gets an unsigned 64-bit integer at the specified byte offset from the
+     * pointer. */
     getBigUint64(offset?: number): PointerValue;
-    /** Gets a signed 64-bit integer at the specified byte offset from the pointer. */
+    /** Gets a signed 64-bit integer at the specified byte offset from the
+     * pointer. */
     getBigInt64(offset?: number): PointerValue;
-    /** Gets a signed 32-bit float at the specified byte offset from the pointer. */
+    /** Gets a signed 32-bit float at the specified byte offset from the
+     * pointer. */
     getFloat32(offset?: number): number;
-    /** Gets a signed 64-bit float at the specified byte offset from the pointer. */
+    /** Gets a signed 64-bit float at the specified byte offset from the
+     * pointer. */
     getFloat64(offset?: number): number;
-    /** Gets a C string (null terminated string) at the specified byte offset from the pointer. */
+    /** Gets a C string (`null` terminated string) at the specified byte offset
+     * from the pointer. */
     getCString(offset?: number): string;
-    /** Gets a C string (null terminated string) at the specified byte offset from the specified pointer. */
+    /** Gets a C string (`null` terminated string) at the specified byte offset
+     * from the specified pointer. */
     static getCString(pointer: PointerValue, offset?: number): string;
-    /** Gets an ArrayBuffer of length `byteLength` at the specified byte offset from the pointer. */
+    /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
+     * offset from the pointer. */
     getArrayBuffer(byteLength: number, offset?: number): ArrayBuffer;
-    /** Gets an ArrayBuffer of length `byteLength` at the specified byte offset from the specified pointer. */
+    /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
+     * offset from the specified pointer. */
     static getArrayBuffer(
       pointer: PointerValue,
       byteLength: number,
       offset?: number,
     ): ArrayBuffer;
-    /** Copies the memory of the pointer into a typed array. Length is determined from the typed array's `byteLength`. Also takes optional byte offset from the pointer. */
+    /** Copies the memory of the pointer into a typed array.
+     *
+     * Length is determined from the typed array's `byteLength`.
+     *
+     * Also takes optional byte offset from the pointer. */
     copyInto(destination: BufferSource, offset?: number): void;
-    /** Copies the memory of the specified pointer into a typed array. Length is determined from the typed array's `byteLength`. Also takes optional byte offset from the pointer. */
+    /** Copies the memory of the specified pointer into a typed array.
+     *
+     * Length is determined from the typed array's `byteLength`.
+     *
+     * Also takes optional byte offset from the pointer. */
     static copyInto(
       pointer: PointerValue,
       destination: BufferSource,
@@ -691,34 +791,43 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * An unsafe pointer to a function, for calling functions that are not
-   * present as symbols.
+   * An unsafe pointer to a function, for calling functions that are not present
+   * as symbols.
    *
    * @category FFI
    */
   export class UnsafeFnPointer<Fn extends ForeignFunction> {
+    /** The pointer to the function. */
     pointer: PointerValue;
+    /** The definition of the function. */
     definition: Fn;
 
     constructor(pointer: PointerValue, definition: Fn);
 
+    /** Call the foreign function. */
     call: FromForeignFunction<Fn>;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * Definition of a unsafe callback function.
+   *
    * @category FFI
    */
   export interface UnsafeCallbackDefinition<
     Parameters extends readonly NativeType[] = readonly NativeType[],
     Result extends NativeResultType = NativeResultType,
   > {
+    /** The parameters of the callbacks. */
     parameters: Parameters;
+    /** The current result of the callback. */
     result: Result;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * An unsafe callback function.
+   *
    * @category FFI
    */
   type UnsafeCallbackFunction<
@@ -730,13 +839,13 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * An unsafe function pointer for passing JavaScript functions
-   * as C function pointers to ffi calls.
+   * An unsafe function pointer for passing JavaScript functions as C function
+   * pointers to foreign function calls.
    *
    * The function pointer remains valid until the `close()` method is called.
    *
-   * The callback can be explicitly ref'ed and deref'ed to stop Deno's
-   * process from exiting.
+   * The callback can be explicitly referenced via `ref()` and dereferenced via
+   * `deref()` to stop Deno's process from exiting.
    *
    * @category FFI
    */
@@ -751,35 +860,39 @@ declare namespace Deno {
       >,
     );
 
+    /** The pointer to the unsafe callback. */
     pointer: PointerValue;
+    /** The definition of the unsafe callback. */
     definition: Definition;
+    /** The callback function. */
     callback: UnsafeCallbackFunction<
       Definition["parameters"],
       Definition["result"]
     >;
 
     /**
-     * Adds one to this callback's reference counting and returns the
-     * new reference count.
+     * Adds one to this callback's reference counting and returns the new
+     * reference count.
      *
-     * If the callback's reference count becomes non-zero, it will keep
-     * Deno's process from exiting.
+     * If the callback's reference count is non-zero, it will keep Deno's
+     * process from exiting.
      */
     ref(): number;
 
     /**
-     * Removes one from this callback's reference counting and returns
-     * the new reference count.
+     * Removes one from this callback's reference counting and returns the new
+     * reference count.
      *
-     * If the callback's reference counter becomes zero, it will no longer
-     * keep Deno's process from exiting.
+     * If the callback's reference counter is zero, it will no longer keep
+     * Deno's process from exiting.
      */
     unref(): number;
 
     /**
-     * Removes the C function pointer associated with the UnsafeCallback.
-     * Continuing to use the instance after calling this object will lead to errors
-     * and crashes.
+     * Removes the C function pointer associated with this instance.
+     *
+     * Continuing to use the instance after calling this object will lead to
+     * errors and crashes.
      *
      * Calling this method will also immediately set the callback's reference
      * counting to zero and it will no longer keep Deno's process from exiting.
@@ -789,20 +902,70 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * A dynamic library resource
+   * A dynamic library resource.  Use {@linkcode Deno.dlopen} to load a dynamic
+   * library and return this interface.
    *
    * @category FFI
    */
   export interface DynamicLibrary<S extends ForeignLibraryInterface> {
-    /** All of the registered library along with functions for calling them */
+    /** All of the registered library along with functions for calling them. */
     symbols: StaticForeignLibraryInterface<S>;
+    /** Removes the pointers associated with the library symbols.
+     *
+     * Continuing to use symbols that are part of the library will lead to
+     * errors and crashes.
+     *
+     * Calling this method will also immediately set any references to zero and
+     * will no longer keep Deno's process from exiting.
+     */
     close(): void;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Opens a dynamic library and registers symbols
+   * Opens an external dynamic library and registers symbols, making foreign
+   * functions available to be called.
+   *
+   * Requires `allow-ffi` permission. Loading foreign dynamic libraries can in
+   * theory bypass all of the sandbox permissions. While it is a separate
+   * permission users should acknowledge in practice that is effectively the
+   * same as running with the `allow-all` permission.
    *
+   * An example, given a C library which exports a foreign function named
+   * `add()`:
+   *
+   * ```ts
+   * // Determine library extension based on
+   * // your OS.
+   * let libSuffix = "";
+   * switch (Deno.build.os) {
+   *   case "windows":
+   *     libSuffix = "dll";
+   *     break;
+   *   case "darwin":
+   *     libSuffix = "dylib";
+   *     break;
+   *   default:
+   *     libSuffix = "so";
+   *     break;
+   * }
+   *
+   * const libName = `./libadd.${libSuffix}`;
+   * // Open library and define exported symbols
+   * const dylib = Deno.dlopen(
+   *   libName,
+   *   {
+   *     "add": { parameters: ["isize", "isize"], result: "isize" },
+   *   } as const,
+   * );
+   *
+   * // Call the symbol `add`
+   * const result = dylib.symbols.add(35, 34); // 69
+   *
+   * console.log(`Result from external addition of 35 and 34: ${result}`);
+   * ```
+   *
+   * @tags allow-ffi
    * @category FFI
    */
   export function dlopen<S extends ForeignLibraryInterface>(
@@ -812,23 +975,76 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * These are unstable options which can be used with {@linkcode Deno.run}.
+   */
+  interface UnstableRunOptions extends RunOptions {
+    /** If `true`, clears the environment variables before executing the
+     * sub-process.  Defaults to `false`. */
+    clearEnv?: boolean;
+    /** For POSIX systems, sets the group ID for the sub process. */
+    gid?: number;
+    /** For POSIX systems, sets the user ID for the sub process. */
+    uid?: number;
+  }
+
+  /** **UNSTABLE**: New API, yet to be vetted.
+   *
+   * Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`,
+   * an array of program arguments, the first of which is the binary.
+   *
+   * ```ts
+   * const p = Deno.run({
+   *   cmd: ["curl", "https://example.com"],
+   * });
+   * const status = await p.status();
+   * ```
+   *
+   * Subprocess uses same working directory as parent process unless `opt.cwd`
+   * is specified.
+   *
+   * Environmental variables from parent process can be cleared using `opt.clearEnv`.
+   * Doesn't guarantee that only `opt.env` variables are present,
+   * as the OS may set environmental variables for processes.
+   *
+   * Environmental variables for subprocess can be specified using `opt.env`
+   * mapping.
+   *
+   * `opt.uid` sets the child process’s user ID. This translates to a setuid call
+   * in the child process. Failure in the setuid call will cause the spawn to fail.
+   *
+   * `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process.
+   * This has the same semantics as the uid field.
+   *
+   * By default subprocess inherits stdio of parent process. To change
+   * this this, `opt.stdin`, `opt.stdout`, and `opt.stderr` can be set
+   * independently to a resource ID (_rid_) of an open file, `"inherit"`,
+   * `"piped"`, or `"null"`:
+   *
+   * - _number_: the resource ID of an open file/resource. This allows you to
+   *   read or write to a file.
+   * - `"inherit"`: The default if unspecified. The subprocess inherits from the
+   *   parent.
+   * - `"piped"`: A new pipe should be arranged to connect the parent and child
+   *   sub-process.
+   * - `"null"`: This stream will be ignored. This is the equivalent of attaching
+   *   the stream to `/dev/null`.
+   *
+   * Details of the spawned process are returned as an instance of
+   * {@linkcode Deno.Process}.
+   *
+   * Requires `allow-run` permission.
+   *
+   * @tags allow-run
    * @category Sub Process
    */
-  export function run<
-    T extends RunOptions & {
-      clearEnv?: boolean;
-      gid?: number;
-      uid?: number;
-    } = RunOptions & {
-      clearEnv?: boolean;
-      gid?: number;
-      uid?: number;
-    },
-  >(opt: T): Process<T>;
+  export function run<T extends UnstableRunOptions = UnstableRunOptions>(
+    opt: T,
+  ): Process<T>;
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * A custom HttpClient for use with `fetch`.
+   * A custom `HttpClient` for use with {@linkcode fetch} function. This is
+   * designed to allow custom certificates or proxies to be used with `fetch()`.
    *
    * ```ts
    * const caCert = await Deno.readTextFile("./ca.pem");
@@ -838,14 +1054,16 @@ declare namespace Deno {
    *
    * @category Fetch API
    */
-  export class HttpClient {
+  export interface HttpClient {
+    /** The resource ID associated with the client. */
     rid: number;
+    /** Close the HTTP client. */
     close(): void;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * The options used when creating a [HttpClient].
+   * The options used when creating a {@linkcode Deno.HttpClient}.
    *
    * @category Fetch API
    */
@@ -865,25 +1083,37 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * The definition of a proxy when specifying
+   * {@linkcode Deno.CreateHttpClientOptions}.
+   *
    * @category Fetch API
    */
   export interface Proxy {
+    /** The string URL of the proxy server to use. */
     url: string;
+    /** The basic auth credentials to be used against the proxy server. */
     basicAuth?: BasicAuth;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * Basic authentication credentials to be used with a {@linkcode Deno.Proxy}
+   * server when specifying {@linkcode Deno.CreateHttpClientOptions}.
+   *
    * @category Fetch API
    */
   export interface BasicAuth {
+    /** The username to be used against the proxy server. */
     username: string;
+    /** The password to be used against the proxy server. */
     password: string;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Create a custom HttpClient for to use with `fetch`.
+   * Create a custom HttpClient for to use with {@linkcode fetch}. This is an
+   * extension of the web platform Fetch API which allows Deno to use custom
+   * TLS certificates and connect via a proxy while using `fetch()`.
    *
    * ```ts
    * const caCert = await Deno.readTextFile("./ca.pem");
@@ -892,7 +1122,9 @@ declare namespace Deno {
    * ```
    *
    * ```ts
-   * const client = Deno.createHttpClient({ proxy: { url: "http://myproxy.com:8080" } });
+   * const client = Deno.createHttpClient({
+   *   proxy: { url: "http://myproxy.com:8080" }
+   * });
    * const response = await fetch("https://myserver.com", { client });
    * ```
    *
@@ -909,35 +1141,48 @@ declare namespace Deno {
    * @category Network
    */
   export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> {
-    /** Waits for and resolves to the next message to the `UDPConn`. */
+    /** Waits for and resolves to the next message to the instance.
+     *
+     * Messages are received in the format of a tuple containing the data array
+     * and the address information.
+     */
     receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>;
-    /** Sends a message to the target. */
+    /** Sends a message to the target via the connection. The method resolves
+     * with the number of bytes sent. */
     send(p: Uint8Array, addr: Addr): Promise<number>;
     /** Close closes the socket. Any pending message promises will be rejected
      * with errors. */
     close(): void;
-    /** Return the address of the `UDPConn`. */
+    /** Return the address of the instance. */
     readonly addr: Addr;
     [Symbol.asyncIterator](): AsyncIterableIterator<[Uint8Array, Addr]>;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * Unstable options which can be set when opening a Unix listener via
+   * {@linkcode Deno.listen} or {@linkcode Deno.listenDatagram}.
+   *
    * @category Network
    */
   export interface UnixListenOptions {
-    /** A Path to the Unix Socket. */
+    /** A path to the Unix Socket. */
     path: string;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * Unstable options which can be set when opening a datagram listener via
+   * {@linkcode Deno.listenDatagram}.
+   *
    * @category Network
    */
   export interface UdpListenOptions extends ListenOptions {
     /** When `true` the specified address will be reused, even if another
      * process has already bound a socket on it. This effectively steals the
-     * socket from the listener. Defaults to `false`. */
+     * socket from the listener.
+     *
+     * Defaults to `false`. */
     reuseAddress?: boolean;
   }
 
@@ -1030,12 +1275,26 @@ declare namespace Deno {
    * @tags allow-net, allow-read
    * @category Network
    */
-  export function connect(
-    options: ConnectOptions,
-  ): Promise<TcpConn>;
-  export function connect(
-    options: UnixConnectOptions,
-  ): Promise<UnixConn>;
+  export function connect(options: ConnectOptions): Promise<TcpConn>;
+  /** **UNSTABLE**: New API, yet to be vetted.
+   *
+   * Connects to the hostname (default is "127.0.0.1") and port on the named
+   * transport (default is "tcp"), and resolves to the connection (`Conn`).
+   *
+   * ```ts
+   * const conn1 = await Deno.connect({ port: 80 });
+   * const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 });
+   * const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 });
+   * const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" });
+   * const conn5 = await Deno.connect({ path: "/foo/bar.sock", transport: "unix" });
+   * ```
+   *
+   * Requires `allow-net` permission for "tcp" and `allow-read` for "unix".
+   *
+   * @tags allow-net, allow-read
+   * @category Network
+   */
+  export function connect(options: UnixConnectOptions): Promise<UnixConn>;
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
@@ -1164,8 +1423,8 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Acquire an advisory file-system lock for the provided file. `exclusive`
-   * defaults to `false`.
+   * Acquire an advisory file-system lock synchronously for the provided file.
+   * `exclusive` defaults to `false`.
    *
    * @category File System
    */
@@ -1181,7 +1440,7 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Release an advisory file-system lock for the provided file.
+   * Release an advisory file-system lock for the provided file synchronously.
    *
    * @category File System
    */
@@ -1201,24 +1460,28 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * Options which can be set when calling {@linkcode Deno.serve}.
+   *
    * @category HTTP Server
    */
   export interface ServeOptions extends Partial<Deno.ListenOptions> {
-    /** An AbortSignal to close the server and all connections. */
+    /** An {@linkcode AbortSignal} to close the server and all connections. */
     signal?: AbortSignal;
 
-    /** Sets SO_REUSEPORT on Linux. */
+    /** Sets `SO_REUSEPORT` on POSIX systems. */
     reusePort?: boolean;
 
     /** The handler to invoke when route handlers throw an error. */
     onError?: (error: unknown) => Response | Promise<Response>;
 
-    /** The callback which is called when the server started listening */
+    /** The callback which is called when the server starts listening. */
     onListen?: (params: { hostname: string; port: number }) => void;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * Additional options which are used when opening a TLS (HTTPS) server.
+   *
    * @category HTTP Server
    */
   export interface ServeTlsOptions extends ServeOptions {
@@ -1243,25 +1506,25 @@ declare namespace Deno {
    * Serves HTTP requests with the given handler.
    *
    * You can specify an object with a port and hostname option, which is the
-   * address to listen on. The default is port 9000 on hostname "127.0.0.1".
+   * address to listen on. The default is port `9000` on hostname `"127.0.0.1"`.
    *
-   * The below example serves with the port 9000.
+   * The below example serves with the port `9000`.
    *
    * ```ts
    * Deno.serve((_req) => new Response("Hello, world"));
    * ```
    *
    * You can change the address to listen on using the `hostname` and `port`
-   * options. The below example serves on port 3000.
+   * options. The below example serves on port `3000`.
    *
    * ```ts
    * Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world"));
    * ```
    *
-   * You can stop the server with an AbortSignal. The abort signal needs to be
-   * passed as the `signal` option in the options bag. The server aborts when
-   * the abort signal is aborted. To wait for the server to close, await the
-   * promise returned from the `Deno.serve` API.
+   * You can stop the server with an {@linkcode AbortSignal}. The abort signal
+   * needs to be passed as the `signal` option in the options bag. The server
+   * aborts when the abort signal is aborted. To wait for the server to close,
+   * await the promise returned from the `Deno.serve` API.
    *
    * ```ts
    * const ac = new AbortController();
@@ -1273,9 +1536,9 @@ declare namespace Deno {
    * ac.abort();
    * ```
    *
-   * By default `Deno.serve` prints the message `Listening on http://<hostname>:<port>/`
-   * on start up. If you like to change this behaviour, you can specify a custom
-   * `onListen` callback.
+   * By default `Deno.serve` prints the message
+   * `Listening on http://<hostname>:<port>/` on listening. If you like to
+   * change this behavior, you can specify a custom `onListen` callback.
    *
    * ```ts
    * Deno.serve({
@@ -1301,19 +1564,137 @@ declare namespace Deno {
     handler: ServeHandler,
     options?: ServeOptions | ServeTlsOptions,
   ): Promise<void>;
+  /** **UNSTABLE**: New API, yet to be vetted.
+   *
+   * Serves HTTP requests with the given handler.
+   *
+   * You can specify an object with a port and hostname option, which is the
+   * address to listen on. The default is port `9000` on hostname `"127.0.0.1"`.
+   *
+   * The below example serves with the port `9000`.
+   *
+   * ```ts
+   * Deno.serve((_req) => new Response("Hello, world"));
+   * ```
+   *
+   * You can change the address to listen on using the `hostname` and `port`
+   * options. The below example serves on port `3000`.
+   *
+   * ```ts
+   * Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world"));
+   * ```
+   *
+   * You can stop the server with an {@linkcode AbortSignal}. The abort signal
+   * needs to be passed as the `signal` option in the options bag. The server
+   * aborts when the abort signal is aborted. To wait for the server to close,
+   * await the promise returned from the `Deno.serve` API.
+   *
+   * ```ts
+   * const ac = new AbortController();
+   *
+   * Deno.serve({ signal: ac.signal }, (_req) => new Response("Hello, world"))
+   *  .then(() => console.log("Server closed"));
+   *
+   * console.log("Closing server...");
+   * ac.abort();
+   * ```
+   *
+   * By default `Deno.serve` prints the message
+   * `Listening on http://<hostname>:<port>/` on listening. If you like to
+   * change this behavior, you can specify a custom `onListen` callback.
+   *
+   * ```ts
+   * Deno.serve({
+   *   onListen({ port, hostname }) {
+   *     console.log(`Server started at http://${hostname}:${port}`);
+   *     // ... more info specific to your server ..
+   *   },
+   *   handler: (_req) => new Response("Hello, world"),
+   * });
+   * ```
+   *
+   * To enable TLS you must specify the `key` and `cert` options.
+   *
+   * ```ts
+   * const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n";
+   * const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";
+   * Deno.serve({ cert, key }, (_req) => new Response("Hello, world"));
+   * ```
+   *
+   * @category HTTP Server
+   */
   export function serve(
     options: ServeOptions | ServeTlsOptions,
     handler: ServeHandler,
   ): Promise<void>;
+  /** **UNSTABLE**: New API, yet to be vetted.
+   *
+   * Serves HTTP requests with the given handler.
+   *
+   * You can specify an object with a port and hostname option, which is the
+   * address to listen on. The default is port `9000` on hostname `"127.0.0.1"`.
+   *
+   * The below example serves with the port `9000`.
+   *
+   * ```ts
+   * Deno.serve((_req) => new Response("Hello, world"));
+   * ```
+   *
+   * You can change the address to listen on using the `hostname` and `port`
+   * options. The below example serves on port `3000`.
+   *
+   * ```ts
+   * Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world"));
+   * ```
+   *
+   * You can stop the server with an {@linkcode AbortSignal}. The abort signal
+   * needs to be passed as the `signal` option in the options bag. The server
+   * aborts when the abort signal is aborted. To wait for the server to close,
+   * await the promise returned from the `Deno.serve` API.
+   *
+   * ```ts
+   * const ac = new AbortController();
+   *
+   * Deno.serve({ signal: ac.signal }, (_req) => new Response("Hello, world"))
+   *  .then(() => console.log("Server closed"));
+   *
+   * console.log("Closing server...");
+   * ac.abort();
+   * ```
+   *
+   * By default `Deno.serve` prints the message
+   * `Listening on http://<hostname>:<port>/` on listening. If you like to
+   * change this behavior, you can specify a custom `onListen` callback.
+   *
+   * ```ts
+   * Deno.serve({
+   *   onListen({ port, hostname }) {
+   *     console.log(`Server started at http://${hostname}:${port}`);
+   *     // ... more info specific to your server ..
+   *   },
+   *   handler: (_req) => new Response("Hello, world"),
+   * });
+   * ```
+   *
+   * To enable TLS you must specify the `key` and `cert` options.
+   *
+   * ```ts
+   * const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n";
+   * const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n";
+   * Deno.serve({ cert, key }, (_req) => new Response("Hello, world"));
+   * ```
+   *
+   * @category HTTP Server
+   */
   export function serve(
     options: ServeInit & (ServeOptions | ServeTlsOptions),
   ): Promise<void>;
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Allows "hijacking" the connection that the request is associated with.
-   * This can be used to implement protocols that build on top of HTTP (eg.
-   * WebSockets).
+   * Allows "hijacking" the connection that the request is associated with. This
+   * can be used to implement protocols that build on top of HTTP (eg.
+   * {@linkcode WebSocket}).
    *
    * The returned promise returns underlying connection and first packet
    * received. The promise shouldn't be awaited before responding to the
@@ -1328,8 +1709,8 @@ declare namespace Deno {
    * }
    * ```
    *
-   * This method can only be called on requests originating the `Deno.serveHttp`
-   * server.
+   * This method can only be called on requests originating the
+   * {@linkcode Deno.serveHttp} server.
    *
    * @category HTTP Server
    */
@@ -1341,15 +1722,16 @@ declare namespace Deno {
    *
    * Allows "hijacking" the connection that the request is associated with.
    * This can be used to implement protocols that build on top of HTTP (eg.
-   * WebSockets).
-
-   * Unlike `Deno.upgradeHttp` this function does not require that you respond
-   * to the request with a `Response` object. Instead this function returns
-   * the underlying connection and first packet received immediately, and then
-   * the caller is responsible for writing the response to the connection.
+   * {@linkcode WebSocket}).
+   *
+   * Unlike {@linkcode Deno.upgradeHttp} this function does not require that you
+   * respond to the request with a {@linkcode Response} object. Instead this
+   * function returns the underlying connection and first packet received
+   * immediately, and then the caller is responsible for writing the response to
+   * the connection.
    *
-   * This method can only be called on requests originating the `Deno.serve`
-   * server.
+   * This method can only be called on requests originating the
+   * {@linkcode Deno.serve} server.
    *
    * @category HTTP Server
    */
@@ -1357,6 +1739,9 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * Options which can be set when calling {@linkcode Deno.spawn},
+   * {@linkcode Deno.spawnSync}, and {@linkcode Deno.spawnChild}.
+   *
    * @category Sub Process
    */
   export interface SpawnOptions {
@@ -1364,40 +1749,50 @@ declare namespace Deno {
     args?: string[];
     /**
      * The working directory of the process.
-     * If not specified, the cwd of the parent process is used.
+     *
+     * If not specified, the `cwd` of the parent process is used.
      */
     cwd?: string | URL;
     /**
      * Clear environmental variables from parent process.
-     * Doesn't guarantee that only `opt.env` variables are present,
-     * as the OS may set environmental variables for processes.
+     *
+     * Doesn't guarantee that only `env` variables are present, as the OS may
+     * set environmental variables for processes.
      */
     clearEnv?: boolean;
     /** Environmental variables to pass to the subprocess. */
     env?: Record<string, string>;
     /**
-     * Sets the child process’s user ID. This translates to a setuid call
-     * in the child process. Failure in the setuid call will cause the spawn to fail.
+     * Sets the child process’s user ID. This translates to a setuid call in the
+     * child process. Failure in the set uid call will cause the spawn to fail.
      */
     uid?: number;
     /** Similar to `uid`, but sets the group ID of the child process. */
     gid?: number;
     /**
-     * An AbortSignal that allows closing the process using the corresponding
-     * AbortController by sending the process a SIGTERM signal.
-     * Not supported in spawnSync.
+     * An {@linkcode AbortSignal} that allows closing the process using the
+     * corresponding {@linkcode AbortController} by sending the process a
+     * SIGTERM signal.
+     *
+     * Not supported in {@linkcode Deno.spawnSync}.
      */
     signal?: AbortSignal;
 
-    /** Defaults to "null". */
+    /** How `stdin` of the spawned process should be handled.
+     *
+     * Defaults to `"null"`. */
     stdin?: "piped" | "inherit" | "null";
-    /** Defaults to "piped". */
+    /**  How `stdout` of the spawned process should be handled.
+     *
+     * Defaults to `"piped"`. */
     stdout?: "piped" | "inherit" | "null";
-    /** Defaults to "piped". */
+    /**  How `stderr` of the spawned process should be handled.
+     *
+     * Defaults to "piped". */
     stderr?: "piped" | "inherit" | "null";
 
     /** Skips quoting and escaping of the arguments on windows. This option
-     * is ignored on non-windows platforms. Defaults to "false". */
+     * is ignored on non-windows platforms. Defaults to `false`. */
     windowsRawArguments?: boolean;
   }
 
@@ -1408,8 +1803,8 @@ declare namespace Deno {
    * If any stdio options are not set to `"piped"`, accessing the corresponding
    * field on the `Child` or its `SpawnOutput` will throw a `TypeError`.
    *
-   * If stdin is set to `"piped"`, the stdin WritableStream needs to be closed
-   * manually.
+   * If `stdin` is set to `"piped"`, the `stdin` {@linkcode WritableStream}
+   * needs to be closed manually.
    *
    * ```ts
    * const child = Deno.spawnChild(Deno.execPath(), {
@@ -1437,6 +1832,9 @@ declare namespace Deno {
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * The interface for handling a child process returned from
+   * {@linkcode Deno.spawnChild}.
+   *
    * @category Sub Process
    */
   export class Child {
@@ -1447,19 +1845,26 @@ declare namespace Deno {
     /** Get the status of the child. */
     readonly status: Promise<ChildStatus>;
 
-    /** Waits for the child to exit completely, returning all its output and status. */
+    /** Waits for the child to exit completely, returning all its output and
+     * status. */
     output(): Promise<SpawnOutput>;
-    /** Kills the process with given Signal. Defaults to SIGTERM. */
+    /** Kills the process with given {@linkcode Deno.Signal}. Defaults to
+     * `"SIGTERM"`. */
     kill(signo?: Signal): void;
 
+    /** Ensure that the status of the child process prevents the Deno process
+     * from exiting. */
     ref(): void;
+    /** Ensure that the status of the child process does not block the Deno
+     * process from exiting. */
     unref(): void;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
-   * Executes a subprocess, waiting for it to finish and
-   * collecting all of its output.
+   * Executes a subprocess, waiting for it to finish and collecting all of its
+   * output.
+   *
    * Will throw an error if `stdin: "piped"` is passed.
    *
    * If options `stdout` or `stderr` are not set to `"piped"`, accessing the
@@ -1488,6 +1893,7 @@ declare namespace Deno {
    *
    * Synchronously executes a subprocess, waiting for it to finish and
    * collecting all of its output.
+   *
    * Will throw an error if `stdin: "piped"` is passed.
    *
    * If options `stdout` or `stderr` are not set to `"piped"`, accessing the
@@ -1517,23 +1923,38 @@ declare namespace Deno {
    * @category Sub Process
    */
   export interface ChildStatus {
+    /** If the child process exits with a 0 status code, `success` will be set
+     * to `true`, otherwise `false`. */
     success: boolean;
+    /** The exit code of the child process. */
     code: number;
+    /** The signal associated with the child process, present if
+     * {@linkcode Deno.spawn} was called. */
     signal: Signal | null;
   }
 
   /** **UNSTABLE**: New API, yet to be vetted.
    *
+   * The interface returned from calling {@linkcode Deno.spawn} or
+   * {@linkcode Deno.spawnSync} which represents the result of spawning the
+   * child process.
+   *
    * @category Sub Process
    */
   export interface SpawnOutput extends ChildStatus {
-    get stdout(): Uint8Array;
-    get stderr(): Uint8Array;
+    /** The buffered output from the child processes `stdout`. */
+    readonly stdout: Uint8Array;
+    /** The buffered output from the child processes `stderr`. */
+    readonly stderr: Uint8Array;
   }
 }
 
 /** **UNSTABLE**: New API, yet to be vetted.
  *
+ * The [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
+ * which also supports setting a {@linkcode Deno.HttpClient} which provides a
+ * way to connect via proxies and use custom TLS certificates.
+ *
  * @tags allow-net, allow-read
  * @category Fetch API
  */
@@ -1552,10 +1973,13 @@ declare interface WorkerOptions {
    * Configure permissions options to change the level of access the worker will
    * have. By default it will have no permissions. Note that the permissions
    * of a worker can't be extended beyond its parent's permissions reach.
-   * - "inherit" will take the permissions of the thread the worker is created in
-   * - "none" will use the default behavior and have no permission
-   * - You can provide a list of routes relative to the file the worker
-   *   is created in to limit the access of the worker (read/write permissions only)
+   *
+   * - `"inherit"` will take the permissions of the thread the worker is created
+   *   in.
+   * - `"none"` will use the default behavior and have no permission
+   * - A list of routes can be provided that are relative to the file the worker
+   *   is created in to limit the access of the worker (read/write permissions
+   *   only)
    *
    * Example:
    *