From 94bb952729848bf33ad2f6fbf72a89c64534b44b Mon Sep 17 00:00:00 2001
From: Asher Gomez <ashersaupingomez@gmail.com>
Date: Fri, 7 Jun 2024 15:54:15 +1200
Subject: [PATCH] docs(net): complete documentation (#4982)

---
 _tools/check_docs.ts       |  1 +
 net/get_available_port.ts  | 12 ++++++++++--
 net/get_network_address.ts | 14 ++++++--------
 net/mod.ts                 |  8 ++++++++
 4 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts
index 566d437d246c..b5e70eeb15b5 100644
--- a/_tools/check_docs.ts
+++ b/_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",
diff --git a/net/get_available_port.ts b/net/get_available_port.ts
index d6476a5b28ed..7180e66c5344 100644
--- a/net/get_available_port.ts
+++ b/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();
diff --git a/net/get_network_address.ts b/net/get_network_address.ts
index 1976999e1087..e39021964e4f 100644
--- a/net/get_network_address.ts
+++ b/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(
diff --git a/net/mod.ts b/net/mod.ts
index 5575f9c2b583..f86259c23f01 100644
--- a/net/mod.ts
+++ b/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
  */