From 37f13a32323c3ba7ff085e6cf24a6a440b9779ea Mon Sep 17 00:00:00 2001
From: Luca Casonato <lucacasonato@yahoo.com>
Date: Sat, 9 May 2020 20:39:42 +0200
Subject: [PATCH 1/7] Add fs events example

---
 docs/examples/file_system_events.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 docs/examples/file_system_events.md

diff --git a/docs/examples/file_system_events.md b/docs/examples/file_system_events.md
new file mode 100644
index 00000000000000..2abebc33e863fe
--- /dev/null
+++ b/docs/examples/file_system_events.md
@@ -0,0 +1,18 @@
+### File system events
+
+To poll for file system events:
+
+```ts
+const watcher = Deno.watchFs("/");
+for await (const event of watcher) {
+  console.log(">>>> event", event);
+  // { kind: "create", paths: [ "/foo.txt" ] }
+}
+```
+
+Note that the exact ordering of the events can vary between operating systems.
+This feature uses different syscalls depending on the platform:
+
+- Linux: inotify
+- macOS: FSEvents
+- Windows: ReadDirectoryChangesW

From 8a21afe7f17c49dc43ee951911bfaabc01a48509 Mon Sep 17 00:00:00 2001
From: Luca Casonato <lucacasonato@yahoo.com>
Date: Sat, 9 May 2020 20:55:49 +0200
Subject: [PATCH 2/7] Testing docs and renamed file server example

---
 .../{fileserver.md => file_server.md}         |   0
 docs/testing.md                               | 105 ++++++++++++++++++
 docs/toc.json                                 |  10 +-
 3 files changed, 108 insertions(+), 7 deletions(-)
 rename docs/examples/{fileserver.md => file_server.md} (100%)
 create mode 100644 docs/testing.md

diff --git a/docs/examples/fileserver.md b/docs/examples/file_server.md
similarity index 100%
rename from docs/examples/fileserver.md
rename to docs/examples/file_server.md
diff --git a/docs/testing.md b/docs/testing.md
new file mode 100644
index 00000000000000..5f9acff02f9779
--- /dev/null
+++ b/docs/testing.md
@@ -0,0 +1,105 @@
+# Testing
+
+Deno has a built-in test runner that you can use for testing JavaScript or
+TypeScript code.
+
+## Writing tests
+
+To define a test you need to call `Deno.test` with a name and function to be
+tested:
+
+```typescript
+Deno.test("hello world", () => {
+  const x = 1 + 2;
+  if (x !== 3) {
+    throw Error("x should be equal to 3");
+  }
+});
+```
+
+There are some useful assertion utilities at https://deno.land/std/testing to
+make testing easier:
+
+```typescript
+import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
+
+Deno.test("hello world", () => {
+  const x = 1 + 2;
+  assertEquals(x, 3);
+});
+```
+
+### Async functions
+
+You can also test asynchronous code by passing a test function that returns a
+promise. For this you can use the `async` keyword when defining a function:
+
+```typescript
+Deno.test("async hello world", async () => {
+  const x = 1 + 2;
+
+  // await some async task
+  await delay(100);
+
+  if (x !== 3) {
+    throw Error("x should be equal to 3");
+  }
+});
+```
+
+### Resource and async op sanitizers
+
+Certain actions in Deno create resources in the resource table
+([learn more here](../contributing/architecture.md)). These resources should be
+closed after you are done using them.
+
+For each test definition the test runner checks that all resources created in
+this test have been closed. This is to prevent resource 'leaks'. This is enabled
+by default for all tests, but can be disabled by setting the `sanitizeResources`
+boolean to false in the test definition.
+
+The same is true for async operation like interacting with the filesystem. The
+test runner checks that each operation you start in the test is completed before
+the end of the test. This is enabled by default for all tests, but can be
+disabled by setting the `sanitizeOps` boolean to false in the test definition.
+
+```typescript
+Deno.test({
+  name: "leaky test",
+  fn() {
+    Deno.open("hello.txt");
+  },
+  sanitizeResources: false,
+  sanitizeOps: false,
+});
+```
+
+### Ignoring tests
+
+Sometimes you want to ignore tests based on some sort of condition (for example
+you only want a test to run on Windows). For this you can use the `ignore`
+boolean in the test definition. If it is set to true the test will be skipped.
+
+```typescript
+Deno.test({
+  name: "do macOS feature",
+  ignore: Deno.build.os !== "darwin",
+  fn() {
+    doMacOSFeature();
+  },
+});
+```
+
+## Running tests
+
+To run the test, call `deno test` with the file that contains your test
+function:
+
+```bash
+deno test my_test.ts
+```
+
+You can also omit the file name, in which case all tests in the current
+directory (recursively) that match the glob `{*_,}test.{js,ts,jsx,tsx}` will be
+run. If you pass a directory, all files in the directory that match this glob
+will be run.
diff --git a/docs/toc.json b/docs/toc.json
index 061ba66f67dd9c..57180e994b20b4 100644
--- a/docs/toc.json
+++ b/docs/toc.json
@@ -17,7 +17,7 @@
     "name": "The Runtime",
     "children": {
       "stability": "Stability",
-      "program_lifecycle": "Program Lifecycle",
+      "program_lifecycle": "Program lifecycle",
       "compiler_apis": "Compiler APIs",
       "workers": "Workers"
     }
@@ -32,11 +32,7 @@
     }
   },
   "testing": {
-    "name": "Testing",
-    "children": {
-      "writing": "Writing tests",
-      "running": "Running tests"
-    }
+    "name": "Testing"
   },
   "plugins": {
     "name": "Plugins",
@@ -73,7 +69,7 @@
     "name": "Examples",
     "children": {
       "unix_cat": "Unix cat program",
-      "fileserver": "File server",
+      "file_server": "File server",
       "tcp_echo": "TCP echo server",
       "subprocess": "Creating a subprocess",
       "permissions": "Inspecting and revoking permissions",

From c2c8a0343af7bb6618abe021ee2db31133501753 Mon Sep 17 00:00:00 2001
From: Luca Casonato <lucacasonato@yahoo.com>
Date: Sat, 9 May 2020 21:02:10 +0200
Subject: [PATCH 3/7] Unified markdown code types

---
 docs/contributing/building_from_source.md |  6 +++---
 docs/contributing/development_tools.md    |  8 ++++----
 docs/examples/file_server.md              |  2 +-
 docs/examples/tcp_echo.md                 |  2 +-
 docs/examples/unix_cat.md                 |  2 +-
 docs/getting_started/first_steps.md       | 12 ++++++------
 docs/getting_started/typescript.md        |  2 +-
 docs/runtime/program_lifecycle.md         |  2 +-
 docs/testing.md                           | 15 ++++++++-------
 9 files changed, 26 insertions(+), 25 deletions(-)

diff --git a/docs/contributing/building_from_source.md b/docs/contributing/building_from_source.md
index 62bbf230342a47..381ad7b039ab30 100644
--- a/docs/contributing/building_from_source.md
+++ b/docs/contributing/building_from_source.md
@@ -8,7 +8,7 @@ Deno you can download a prebuilt executable (more information in the
 
 Clone on Linux or Mac:
 
-```bash
+```shell
 git clone --recurse-submodules https://github.com/denoland/deno.git
 ```
 
@@ -18,7 +18,7 @@ Extra steps for Windows users:
    (otherwise symlinks would require administrator privileges).
 2. Make sure you are using git version 2.19.2.windows.1 or newer.
 3. Set `core.symlinks=true` before the checkout:
-   ```bash
+   ```shell
    git config --global core.symlinks true
    git clone --recurse-submodules https://github.com/denoland/deno.git
    ```
@@ -77,7 +77,7 @@ about the V8 build.
 
 Build with Cargo:
 
-```bash
+```shell
 # Build:
 cargo build -vv
 
diff --git a/docs/contributing/development_tools.md b/docs/contributing/development_tools.md
index 35bd5a5fbdb8aa..b8aa9505f96abf 100644
--- a/docs/contributing/development_tools.md
+++ b/docs/contributing/development_tools.md
@@ -4,7 +4,7 @@
 
 Test `deno`:
 
-```bash
+```shell
 # Run the whole suite:
 cargo test
 
@@ -14,7 +14,7 @@ cargo test js_unit_tests
 
 Test `std/`:
 
-```bash
+```shell
 cargo test std_tests
 ```
 
@@ -22,13 +22,13 @@ cargo test std_tests
 
 Lint the code:
 
-```bash
+```shell
 ./tools/lint.py
 ```
 
 Format the code:
 
-```bash
+```shell
 ./tools/format.py
 ```
 
diff --git a/docs/examples/file_server.md b/docs/examples/file_server.md
index 3ed9d90e70d1ce..9fbe27bd37cbac 100644
--- a/docs/examples/file_server.md
+++ b/docs/examples/file_server.md
@@ -2,7 +2,7 @@
 
 This one serves a local directory in HTTP.
 
-```bash
+```shell
 deno install --allow-net --allow-read https://deno.land/std/http/file_server.ts
 ```
 
diff --git a/docs/examples/tcp_echo.md b/docs/examples/tcp_echo.md
index d7c2e9e72217d5..360c5faccd58ea 100644
--- a/docs/examples/tcp_echo.md
+++ b/docs/examples/tcp_echo.md
@@ -25,7 +25,7 @@ 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:
 
 ```shell
-$ deno run --allow-net https://deno.land/std/examples/echo_server.ts
+deno run --allow-net https://deno.land/std/examples/echo_server.ts
 ```
 
 To test it, try sending data to it with netcat:
diff --git a/docs/examples/unix_cat.md b/docs/examples/unix_cat.md
index 7534ef0d0f31a9..ca85ea3259a466 100644
--- a/docs/examples/unix_cat.md
+++ b/docs/examples/unix_cat.md
@@ -20,5 +20,5 @@ I/O streams in Deno.
 Try the program:
 
 ```shell
-$ deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
+deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
 ```
diff --git a/docs/getting_started/first_steps.md b/docs/getting_started/first_steps.md
index 74dbae1b42fc83..8c9e4ea0ab37f9 100644
--- a/docs/getting_started/first_steps.md
+++ b/docs/getting_started/first_steps.md
@@ -17,13 +17,13 @@ and use modern features wherever possible.
 Because of this browser compatibility a simple `Hello World` program is actually
 no different to one you can run in the browser:
 
-```typescript
+```ts
 console.log("Welcome to Deno 🦕");
 ```
 
 Try the program:
 
-```bash
+```shell
 deno run https://deno.land/std/examples/welcome.ts
 ```
 
@@ -37,7 +37,7 @@ Just like in the browser you can use the web standard
 [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API to
 make HTTP calls:
 
-```typescript
+```ts
 const url = Deno.args[0];
 const res = await fetch(url);
 
@@ -60,7 +60,7 @@ Lets walk through what this application does:
 
 Try it out:
 
-```bash
+```shell
 deno run https://deno.land/std/examples/curl.ts https://example.com
 ```
 
@@ -71,7 +71,7 @@ programs the permission to do certain 'privileged' actions like network access.
 
 Try it out again with the correct permission flag:
 
-```bash
+```shell
 deno run --allow-net=example.com https://deno.land/std/examples/curl.ts https://example.com
 ```
 
@@ -103,7 +103,7 @@ I/O streams in Deno.
 
 Try the program:
 
-```bash
+```shell
 deno run --allow-read https://deno.land/std/examples/cat.ts /etc/passwd
 ```
 
diff --git a/docs/getting_started/typescript.md b/docs/getting_started/typescript.md
index ebe1e5e708cd29..35a513b37d0dc1 100644
--- a/docs/getting_started/typescript.md
+++ b/docs/getting_started/typescript.md
@@ -100,7 +100,7 @@ be provided to Deno on program execution.
 You need to explicitly tell Deno where to look for this configuration by setting
 the `-c` argument when executing your application.
 
-```bash
+```shell
 deno run -c tsconfig.json mod.ts
 ```
 
diff --git a/docs/runtime/program_lifecycle.md b/docs/runtime/program_lifecycle.md
index dda8a06f92bc6e..c7c3c46a39b6ab 100644
--- a/docs/runtime/program_lifecycle.md
+++ b/docs/runtime/program_lifecycle.md
@@ -8,7 +8,7 @@ Listener for `load` events can be asynchronous and will be awaited. Listener for
 
 Example:
 
-```typescript
+```ts
 // main.ts
 import "./imported.ts";
 
diff --git a/docs/testing.md b/docs/testing.md
index 5f9acff02f9779..c661c35040bc16 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -8,7 +8,7 @@ TypeScript code.
 To define a test you need to call `Deno.test` with a name and function to be
 tested:
 
-```typescript
+```ts
 Deno.test("hello world", () => {
   const x = 1 + 2;
   if (x !== 3) {
@@ -20,7 +20,7 @@ Deno.test("hello world", () => {
 There are some useful assertion utilities at https://deno.land/std/testing to
 make testing easier:
 
-```typescript
+```ts
 import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
 
 Deno.test("hello world", () => {
@@ -34,7 +34,7 @@ Deno.test("hello world", () => {
 You can also test asynchronous code by passing a test function that returns a
 promise. For this you can use the `async` keyword when defining a function:
 
-```typescript
+```ts
 Deno.test("async hello world", async () => {
   const x = 1 + 2;
 
@@ -63,7 +63,7 @@ test runner checks that each operation you start in the test is completed before
 the end of the test. This is enabled by default for all tests, but can be
 disabled by setting the `sanitizeOps` boolean to false in the test definition.
 
-```typescript
+```ts
 Deno.test({
   name: "leaky test",
   fn() {
@@ -80,7 +80,7 @@ Sometimes you want to ignore tests based on some sort of condition (for example
 you only want a test to run on Windows). For this you can use the `ignore`
 boolean in the test definition. If it is set to true the test will be skipped.
 
-```typescript
+```ts
 Deno.test({
   name: "do macOS feature",
   ignore: Deno.build.os !== "darwin",
@@ -95,11 +95,12 @@ Deno.test({
 To run the test, call `deno test` with the file that contains your test
 function:
 
-```bash
-deno test my_test.ts
+shell deno test my_test.ts
+
 ```
 
 You can also omit the file name, in which case all tests in the current
 directory (recursively) that match the glob `{*_,}test.{js,ts,jsx,tsx}` will be
 run. If you pass a directory, all files in the directory that match this glob
 will be run.
+```

From 2a02e0161fcd55d6bcfd45161f327d24ad5b1072 Mon Sep 17 00:00:00 2001
From: Luca Casonato <lucacasonato@yahoo.com>
Date: Sat, 9 May 2020 21:02:58 +0200
Subject: [PATCH 4/7] Removed plugin things from toc

---
 docs/toc.json | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/docs/toc.json b/docs/toc.json
index 57180e994b20b4..5369a00652a160 100644
--- a/docs/toc.json
+++ b/docs/toc.json
@@ -34,14 +34,6 @@
   "testing": {
     "name": "Testing"
   },
-  "plugins": {
-    "name": "Plugins",
-    "children": {
-      "how_do_plugins_work": "How do plugins work?",
-      "creating_plugins": "Creating plugins",
-      "using_plugins": "Using plugins"
-    }
-  },
   "tools": {
     "name": "Tools",
     "children": {

From e8b8ce4ec3b31e1dfad1575802361d5e2b03aa55 Mon Sep 17 00:00:00 2001
From: Luca Casonato <lucacasonato@yahoo.com>
Date: Sat, 9 May 2020 22:09:51 +0200
Subject: [PATCH 5/7] Fix links

---
 docs/contributing.md             | 2 +-
 docs/linking_to_external_code.md | 4 ++--
 docs/runtime/stability.md        | 2 +-
 docs/runtime/workers.md          | 3 ++-
 docs/testing.md                  | 2 +-
 docs/tools.md                    | 2 +-
 docs/tools/script_installer.md   | 4 ++--
 7 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/docs/contributing.md b/docs/contributing.md
index df2d1de24a354d..f83756e9b65aa8 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -1,6 +1,6 @@
 # Contributing
 
-- Read the [style guide](contributing/style_guide.md).
+- Read the [style guide](./contributing/style_guide.md).
 
 - Please don't make [the benchmarks](https://deno.land/benchmarks.html) worse.
 
diff --git a/docs/linking_to_external_code.md b/docs/linking_to_external_code.md
index 5484a78065665b..e03bfdfee81ae6 100644
--- a/docs/linking_to_external_code.md
+++ b/docs/linking_to_external_code.md
@@ -1,6 +1,6 @@
 # Linking to third party code
 
-In the [Getting Started](../getting_started) section, we saw that Deno could
+In the [Getting Started](./getting_started.md) section, we saw that Deno could
 execute scripts from URLs. Like browser JavaScript, Deno can import libraries
 directly from URLs. This example uses a URL to import an assertion library:
 
@@ -52,7 +52,7 @@ specifying that path as the `$DENO_DIR` environmental variable at runtime.
 
 By using a lock file (using the `--lock` command line flag) you can ensure
 you're running the code you expect to be. You can learn more about this
-[here](./integrity_checking).
+[here](./linking_to_external_code/integrity_checking.md).
 
 ### How do you import to a specific version?
 
diff --git a/docs/runtime/stability.md b/docs/runtime/stability.md
index a158638b98dc0d..cd7c27039202a9 100644
--- a/docs/runtime/stability.md
+++ b/docs/runtime/stability.md
@@ -10,7 +10,7 @@ are not ready because they are still in draft phase are locked behind the
 - 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)
-  file to the list of TypeScript definitions that are used for typechecking.
+  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
diff --git a/docs/runtime/workers.md b/docs/runtime/workers.md
index 0418f057e09d00..3c39d2cee7f6eb 100644
--- a/docs/runtime/workers.md
+++ b/docs/runtime/workers.md
@@ -20,7 +20,8 @@ new Worker("./worker.js", { type: "classic" });
 
 ### Using Deno in worker
 
-**UNSTABLE**: This feature is unstable and requires `--unstable` flag
+> This is an unstable Deno feature. Learn more about
+> [unstable features](./stability.md).
 
 By default `Deno` namespace is not available in worker scope.
 
diff --git a/docs/testing.md b/docs/testing.md
index c661c35040bc16..47f5d036b4f231 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -50,7 +50,7 @@ Deno.test("async hello world", async () => {
 ### Resource and async op sanitizers
 
 Certain actions in Deno create resources in the resource table
-([learn more here](../contributing/architecture.md)). These resources should be
+([learn more here](./contributing/architecture.md)). These resources should be
 closed after you are done using them.
 
 For each test definition the test runner checks that all resources created in
diff --git a/docs/tools.md b/docs/tools.md
index f3dae49e8d760a..904bf027f6251f 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -6,7 +6,7 @@ and TypeScript:
 <!-- prettier-ignore-start -->
 <!-- prettier incorrectly moves the coming soon links to new lines -->
 
-- [test runner (`deno test`)](../testing)
+- [test runner (`deno test`)](./testing.md)
 - [code formatter (`deno fmt`)](./tools/formatter.md)
 - [bundler (`deno bundle`)](./tools/bundler.md)
 - [debugger (`--debug`)](./tools/debugger.md)
diff --git a/docs/tools/script_installer.md b/docs/tools/script_installer.md
index ffd920cf3c2e53..43ed9d802add3f 100644
--- a/docs/tools/script_installer.md
+++ b/docs/tools/script_installer.md
@@ -62,8 +62,8 @@ The above command creates an executable called `file_server` that runs with
 write and read permissions and binds to port 8080.
 
 For good practice, use the
-[`import.meta.main`](#testing-if-current-file-is-the-main-program) idiom to
-specify the entry point in an executable script.
+[`import.meta.main`](../examples/testing_if_main.md) idiom to specify the
+entry point in an executable script.
 
 Example:
 

From 9ca85a5d353b4ea869606fee5d3f03b731293885 Mon Sep 17 00:00:00 2001
From: Luca Casonato <lucacasonato@yahoo.com>
Date: Sat, 9 May 2020 22:23:41 +0200
Subject: [PATCH 6/7] Fix typo

---
 docs/testing.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/testing.md b/docs/testing.md
index 47f5d036b4f231..d6f59e3ec38550 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -95,12 +95,11 @@ Deno.test({
 To run the test, call `deno test` with the file that contains your test
 function:
 
-shell deno test my_test.ts
-
+```shell
+deno test my_test.ts
 ```
 
 You can also omit the file name, in which case all tests in the current
 directory (recursively) that match the glob `{*_,}test.{js,ts,jsx,tsx}` will be
 run. If you pass a directory, all files in the directory that match this glob
 will be run.
-```

From a2f42402592cb21f0242ca73683b42b5d0468202 Mon Sep 17 00:00:00 2001
From: Luca Casonato <lucacasonato@yahoo.com>
Date: Sat, 9 May 2020 22:24:07 +0200
Subject: [PATCH 7/7] fmt

---
 docs/tools/script_installer.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/tools/script_installer.md b/docs/tools/script_installer.md
index 43ed9d802add3f..6badd6436beae2 100644
--- a/docs/tools/script_installer.md
+++ b/docs/tools/script_installer.md
@@ -61,9 +61,8 @@ $ deno install --allow-net --allow-read https://deno.land/std/http/file_server.t
 The above command creates an executable called `file_server` that runs with
 write and read permissions and binds to port 8080.
 
-For good practice, use the
-[`import.meta.main`](../examples/testing_if_main.md) idiom to specify the
-entry point in an executable script.
+For good practice, use the [`import.meta.main`](../examples/testing_if_main.md)
+idiom to specify the entry point in an executable script.
 
 Example: