docs(net): complete documentation (#4982)

_tools/check_docs.ts

@@ -48,6 +48,7 @@ const ENTRY_POINTS = [
   "../internal/mod.ts",
   "../jsonc/mod.ts",
   "../media_types/mod.ts",
+  "../net/mod.ts",
   "../path/mod.ts",
   "../path/posix/mod.ts",
   "../path/windows/mod.ts",

net/get_available_port.ts

@@ -5,6 +5,11 @@ export interface GetAvailablePortOptions {
   /**
    * A port to check availability of first. If the port isn't available, fall
    * back to another port.
+   *
+   * Defaults to port 0, which will let the operating system choose an available
+   * port.
+   *
+   * @default {0}
    */
   preferredPort?: number;
 }
@@ -12,8 +17,11 @@ export interface GetAvailablePortOptions {
 /**
  * Returns an available network port.
  *
- * @example
- * ```ts
+ * @param options Options for getting an available port.
+ * @returns An available network port.
+ *
+ * @example Usage
+ * ```ts no-eval no-assert
  * import { getAvailablePort } from "@std/net/get-available-port";
  *
  * const port = getAvailablePort();

net/get_network_address.ts

@@ -13,23 +13,21 @@
  * @returns The IPv4 network address of the machine.
  *
  * @example Get the IPv4 network address (default)
- * ```ts
+ * ```ts no-assert no-eval
  * import { getNetworkAddress } from "@std/net/get-network-address";
- * import { assert } from "@std/assert/assert";
  *
- * const address = getNetworkAddress();
+ * const hostname = getNetworkAddress();
  *
- * assert(address !== undefined);
+ * Deno.serve({ port: 0, hostname }, () => new Response("Hello, world!"));
  * ```
  *
  * @example Get the IPv6 network address
- * ```ts
+ * ```ts no-assert no-eval
  * import { getNetworkAddress } from "@std/net/get-network-address";
- * import { assert } from "@std/assert/assert";
  *
- * const address = getNetworkAddress("IPv6");
+ * const hostname = getNetworkAddress("IPv6");
  *
- * assert(address !== undefined);
+ * Deno.serve({ port: 0, hostname }, () => new Response("Hello, world!"));
  * ```
  */
 export function getNetworkAddress(

net/mod.ts

@@ -3,6 +3,14 @@
 /**
  * Network utilities.
  *
+ * ```ts no-assert no-eval
+ * import { getNetworkAddress, getAvailablePort } from "@std/net";
+ *
+ * console.log(`My network IP address is ${getNetworkAddress()}`);
+ *
+ * Deno.serve({ port: getAvailablePort() }, () => new Response("Hello, world!"));
+ * ```
+ *
  * @module
  */