From 27708fe87316d11b8d99459db257d381ee049430 Mon Sep 17 00:00:00 2001
From: Chris Knight <cknight1234@gmail.com>
Date: Wed, 27 May 2020 03:12:02 +0100
Subject: [PATCH] doc: various runtime doc updates (#5885)

---
 docs/runtime.md                   |  5 ++++-
 docs/runtime/program_lifecycle.md | 12 ++++++++--
 docs/runtime/stability.md         | 21 +++++++++++++-----
 docs/runtime/workers.md           | 37 ++++++++++++++++++++++---------
 4 files changed, 56 insertions(+), 19 deletions(-)

diff --git a/docs/runtime.md b/docs/runtime.md
index 735ff328e9..50cca6def8 100644
--- a/docs/runtime.md
+++ b/docs/runtime.md
@@ -9,8 +9,11 @@ on
 For APIs where a web standard already exists, like `fetch` for HTTP requests,
 Deno uses these rather than inventing a new proprietary API.
 
-The documentation for all of these Web APIs can be found on
+The detailed documentation for implemented Web APIs can be found on
 [doc.deno.land](https://doc.deno.land/https/raw.githubusercontent.com/denoland/deno/master/cli/js/lib.deno.shared_globals.d.ts).
+Additionally, a full list of the Web APIs which Deno implements is also
+available
+[in the repository](https://github.com/denoland/deno/blob/master/cli/js/web/README.md).
 
 The TypeScript definitions for the implemented web APIs can be found in the
 [`lib.deno.shared_globals.d.ts`](https://github.com/denoland/deno/blob/master/cli/js/lib.deno.shared_globals.d.ts)
diff --git a/docs/runtime/program_lifecycle.md b/docs/runtime/program_lifecycle.md
index 4a94d6724b..7f60350485 100644
--- a/docs/runtime/program_lifecycle.md
+++ b/docs/runtime/program_lifecycle.md
@@ -8,8 +8,9 @@ for `unload` events need to be synchronous. Both events cannot be cancelled.
 
 Example:
 
+**main.ts**
+
 ```ts
-// main.ts
 import "./imported.ts";
 
 const handler = (e: Event): void => {
@@ -29,8 +30,11 @@ window.onunload = (e: Event): void => {
 };
 
 console.log("log from main script");
+```
 
-// imported.ts
+**imported.ts**
+
+```ts
 const handler = (e: Event): void => {
   console.log(`got ${e.type} event in event handler (imported)`);
 };
@@ -68,3 +72,7 @@ got unload event in event handler (main)
 All listeners added using `window.addEventListener` were run, but
 `window.onload` and `window.onunload` defined in `main.ts` overrode handlers
 defined in `imported.ts`.
+
+In other words, you can register multiple `window.addEventListener` `"load"` or
+`"unload"` events, but only the last loaded `window.onload` or `window.onunload`
+events will be executed.
diff --git a/docs/runtime/stability.md b/docs/runtime/stability.md
index 7fcc0f0b0d..298a788d46 100644
--- a/docs/runtime/stability.md
+++ b/docs/runtime/stability.md
@@ -5,17 +5,28 @@ strive to make code working under 1.0.0 continue to work in future versions.
 
 However, not all of Deno's features are ready for production yet. Features which
 are not ready, because they are still in draft phase, are locked behind the
-`--unstable` command line flag. Passing this flag does a few things:
+`--unstable` command line flag.
+
+```shell
+deno run --unstable mod_which_uses_unstable_stuff.ts
+```
+
+Passing this flag does a few things:
 
 - It enables the use of unstable APIs during runtime.
 - It adds the
-  [`lib.deno.unstable.d.ts`](https://github.com/denoland/deno/blob/master/cli/js/lib.deno.unstable.d.ts)
+  [`lib.deno.unstable.d.ts`](https://doc.deno.land/https/raw.githubusercontent.com/denoland/deno/master/cli/js/lib.deno.unstable.d.ts)
   file to the list of TypeScript definitions that are used for type checking.
   This includes the output of `deno types`.
 
-You should be aware that unstable APIs have probably **not undergone a security
+You should be aware that many unstable APIs have **not undergone a security
 review**, are likely to have **breaking API changes** in the future, and are
 **not ready for production**.
 
-Furthermore Deno's standard modules (https://deno.land/std/) are not yet stable.
-We version the standard modules differently from the CLI to reflect this.
+### Standard modules
+
+Deno's standard modules (https://deno.land/std/) are not yet stable. We
+currently version the standard modules differently from the CLI to reflect this.
+Note that unlike the `Deno` namespace, the use of the standard modules do not
+require the `--unstable` flag (unless the standard module itself makes use of an
+unstable Deno feature).
diff --git a/docs/runtime/workers.md b/docs/runtime/workers.md
index 89541cee75..110255b8b6 100644
--- a/docs/runtime/workers.md
+++ b/docs/runtime/workers.md
@@ -25,11 +25,15 @@ requires appropriate permission for this action.
 
 For workers using local modules; `--allow-read` permission is required:
 
-```ts
-// main.ts
-new Worker("./worker.ts", { type: "module" });
+**main.ts**
 
-// worker.ts
+```ts
+new Worker("./worker.ts", { type: "module" });
+```
+
+**worker.ts**
+
+```ts
 console.log("hello world");
 self.close();
 ```
@@ -44,11 +48,15 @@ hello world
 
 For workers using remote modules; `--allow-net` permission is required:
 
-```ts
-// main.ts
-new Worker("https://example.com/worker.ts", { type: "module" });
+**main.ts**
 
-// worker.ts
+```ts
+new Worker("https://example.com/worker.ts", { type: "module" });
+```
+
+**worker.ts** (at https[]()://example.com/worker.ts)
+
+```ts
 console.log("hello world");
 self.close();
 ```
@@ -70,20 +78,27 @@ By default the `Deno` namespace is not available in worker scope.
 
 To add the `Deno` namespace pass `deno: true` option when creating new worker:
 
+**main.js**
+
 ```ts
-// main.js
 const worker = new Worker("./worker.js", { type: "module", deno: true });
 worker.postMessage({ filename: "./log.txt" });
+```
 
-// worker.js
+**worker.js**
+
+```ts
 self.onmessage = async (e) => {
   const { filename } = e.data;
   const text = await Deno.readTextFile(filename);
   console.log(text);
   self.close();
 };
+```
 
-// log.txt
+**log.txt**
+
+```
 hello world
 ```