doc: improve Examples (#7428)

1 files changed, 22 insertions, 18 deletions

diff --git a/docs/examples/tcp_echo.md b/docs/examples/tcp_echo.md
index 99e8cbd04..ba70aa795 100644
--- a/docs/examples/tcp_echo.md
+++ b/docs/examples/tcp_echo.md
@@ -1,9 +1,21 @@
-## TCP echo server
+# TCP echo server
+
+## Concepts
+
+- Listening for TCP port connections with
+  [Deno.listen](https://doc.deno.land/builtin/stable#Deno.listen)
+- Use [Deno.copy](https://doc.deno.land/builtin/stable#Deno.copy) to take
+  inbound data and redirect it to be outbound data
+
+## Example
 
 This is an example of a server which accepts connections on port 8080, and
 returns to the client anything it sends.
 
 ```ts
+/**
+ * echo_server.ts
+ */
 const listener = Deno.listen({ port: 8080 });
 console.log("listening on 0.0.0.0:8080");
 for await (const conn of listener) {
@@ -11,24 +23,16 @@ for await (const conn of listener) {
 }
 ```
 
-When this program is started, it throws PermissionDenied error.
-
-```shell
-$ deno run https://deno.land/std@$STD_VERSION/examples/echo_server.ts
-error: Uncaught PermissionDenied: network access to "0.0.0.0:8080", run again with the --allow-net flag
-► $deno$/dispatch_json.ts:40:11
-    at DenoError ($deno$/errors.ts:20:5)
-    ...
-```
-
-For security reasons, Deno does not allow programs to access the network without
-explicit permission. To allow accessing the network, use a command-line flag:
+Run with:
 
 ```shell
-deno run --allow-net https://deno.land/std@$STD_VERSION/examples/echo_server.ts
+deno run --allow-net echo_server.ts
 ```
 
-To test it, try sending data to it with netcat:
+To test it, try sending data to it with
+[netcat](https://en.wikipedia.org/wiki/Netcat) (Linux/MacOS only). Below
+`'hello world'` is sent over the connection, which is then echoed back to the
+user:
 
 ```shell
 $ nc localhost 8080
@@ -36,6 +40,6 @@ hello world
 hello world
 ```
 
-Like the `cat.ts` example, the `copy()` function here also does not make
-unnecessary memory copies. It receives a packet from the kernel and sends back,
-without further complexity.
+Like the [cat.ts example](./unix_cat.md), the `copy()` function here also does
+not make unnecessary memory copies. It receives a packet from the kernel and
+sends back, without further complexity.