doc: improve linking to external code docs (#6158)

4 files changed, 90 insertions, 23 deletions

diff --git a/docs/linking_to_external_code.md b/docs/linking_to_external_code.md
index af46faf5d..ad6cfab09 100644
--- a/docs/linking_to_external_code.md
+++ b/docs/linking_to_external_code.md
@@ -4,13 +4,15 @@ In the [Getting Started](./getting_started.md) section, we saw 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:
 
+**test.ts**
+
 ```ts
 import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
 
 assertEquals("hello", "hello");
 assertEquals("world", "world");
 
-console.log("Asserted! 🎉");
+console.log("Asserted! ✓");
 ```
 
 Try running this:
@@ -21,15 +23,15 @@ Compile file:///mnt/f9/Projects/github.com/denoland/deno/docs/test.ts
 Download https://deno.land/std/testing/asserts.ts
 Download https://deno.land/std/fmt/colors.ts
 Download https://deno.land/std/testing/diff.ts
-Asserted! 🎉
+Asserted! ✓
 ```
 
 Note that we did not have to provide the `--allow-net` flag for this program,
 and yet it accessed the network. The runtime has special access to download
 imports and cache them to disk.
 
-Deno caches remote imports in a special directory specified by the `$DENO_DIR`
-environment variable. It defaults to the system's cache directory if `$DENO_DIR`
+Deno caches remote imports in a special directory specified by the `DENO_DIR`
+environment variable. It defaults to the system's cache directory if `DENO_DIR`
 is not specified. The next time you run the program, no downloads will be made.
 If the program hasn't changed, it won't be recompiled either. The default
 directory is:
@@ -58,6 +60,8 @@ For example, let's say you were using the above assertion library across a large
 project. Rather than importing `"https://deno.land/std/testing/asserts.ts"`
 everywhere, you could create a `deps.ts` file that exports the third-party code:
 
+**deps.ts**
+
 ```ts
 export {
   assert,
diff --git a/docs/linking_to_external_code/import_maps.md b/docs/linking_to_external_code/import_maps.md
index fe3a40cd2..8ed9ef891 100644
--- a/docs/linking_to_external_code/import_maps.md
+++ b/docs/linking_to_external_code/import_maps.md
@@ -16,27 +16,26 @@ Current limitations:
 
 Example:
 
-```js
-// import_map.json
+**import_map.json**
 
+```js
 {
    "imports": {
-      "http/": "https://deno.land/std/http/"
+      "fmt/": "https://deno.land/std@0.55.0/fmt/"
    }
 }
 ```
 
-```ts
-// hello_server.ts
+**color.ts**
 
-import { serve } from "http/server.ts";
+```ts
+import { red } from "fmt/colors.ts";
 
-const body = new TextEncoder().encode("Hello World\n");
-for await (const req of serve(":8000")) {
-  req.respond({ body });
-}
+console.log(red("hello world"));
 ```
 
+Then:
+
 ```shell
-$ deno run --allow-net --importmap=import_map.json --unstable hello_server.ts
+$ deno run --importmap=import-map.json --unstable color.ts
 ```
diff --git a/docs/linking_to_external_code/integrity_checking.md b/docs/linking_to_external_code/integrity_checking.md
index 91d595cda..df0774865 100644
--- a/docs/linking_to_external_code/integrity_checking.md
+++ b/docs/linking_to_external_code/integrity_checking.md
@@ -1,16 +1,48 @@
 ## Integrity checking & lock files
 
+### Introduction
+
+Let's say your module depends on remote module `https://some.url/a.ts`. When you
+compile your module for the first time `a.ts` is retrieved, compiled and cached.
+It will remain this way until you run your module on a new machine (say in
+production) or reload the cache (through `deno cache --reload` for example). But
+what happens if the content in the remote url `https://some.url/a.ts` is
+changed? This could lead to your production module running with different
+dependency code than your local module. Deno's solution to avoid this is to use
+integrity checking and lock files.
+
+### Caching and lock files
+
 Deno can store and check subresource integrity for modules using a small JSON
 file. Use the `--lock=lock.json` to enable and specify lock file checking. To
-update or create a lock use `--lock=lock.json --lock-write`.
+update or create a lock use `--lock=lock.json --lock-write`. The
+`--lock=lock.json` tells Deno what the lock file to use is, while the
+`--lock-write` is used to output dependency hashes to the lock file
+(`--lock-write` must be used in conjunction with `--lock`).
+
+A `lock.json` might look like this, storing a hash of the file against the
+dependency:
+
+```json
+{
+  "https://deno.land/std@v0.50.0/textproto/mod.ts": "3118d7a42c03c242c5a49c2ad91c8396110e14acca1324e7aaefd31a999b71a4",
+  "https://deno.land/std@v0.50.0/io/util.ts": "ae133d310a0fdcf298cea7bc09a599c49acb616d34e148e263bcb02976f80dee",
+  "https://deno.land/std@v0.50.0/async/delay.ts": "35957d585a6e3dd87706858fb1d6b551cb278271b03f52c5a2cb70e65e00c26a",
+   ...
+}
+```
 
 A typical workflow will look like this:
 
+**src/deps.ts**
+
 ```ts
 // Add a new dependency to "src/deps.ts", used somewhere else.
 export { xyz } from "https://unpkg.com/xyz-lib@v0.9.0/lib.ts";
 ```
 
+Then:
+
 ```shell
 # Create/update the lock file "lock.json".
 deno cache --lock=lock.json --lock-write src/deps.ts
@@ -26,8 +58,28 @@ Collaborator on another machine -- in a freshly cloned project tree:
 ```shell
 # Download the project's dependencies into the machine's cache, integrity
 # checking each resource.
-deno cache -r --lock=lock.json src/deps.ts
+deno cache --reload --lock=lock.json src/deps.ts
 
 # Done! You can proceed safely.
 deno test --allow-read src
 ```
+
+### Runtime verification
+
+Like caching above, you can also use the `--lock=lock.json` option during use of
+the `deno run` sub command, validating the integrity of any locked modules
+during the run. Remember that this only validates against dependencies
+previously added to the `lock.json` file. New dependencies will be cached but
+not validated.
+
+You can take this a step further as well by using the `--cached-only` flag to
+require that remote dependencies are already cached.
+
+```shell
+deno run --lock=lock.json --cached-only mod.ts
+```
+
+This will fail if there are any dependencies in the dependency tree for mod.ts
+which are not yet cached.
+
+<!-- TODO - Add detail on dynamic imports -->
diff --git a/docs/linking_to_external_code/reloading_modules.md b/docs/linking_to_external_code/reloading_modules.md
index 94b87b711..01300a5c3 100644
--- a/docs/linking_to_external_code/reloading_modules.md
+++ b/docs/linking_to_external_code/reloading_modules.md
@@ -1,22 +1,34 @@
 ## Reloading modules
 
-You can invalidate your local `DENO_DIR` cache using the `--reload` flag. It's
+By default, a module in the cache will be reused without fetching or
+re-compiling it. Sometimes this is not desirable and you can force deno to
+refetch and recompile modules into the cache. You can invalidate your local
+`DENO_DIR` cache using the `--reload` flag of the `deno cache` subcommand. It's
 usage is described below:
 
-To reload everything
+### To reload everything
 
-`--reload`
+```ts
+deno cache --reload my_module.ts
+
+```
+
+### To reload specific modules
 
 Sometimes we want to upgrade only some modules. You can control it by passing an
 argument to a `--reload` flag.
 
-To reload all standard modules
+To reload all v0.55.0 standard modules
 
-`--reload=https://deno.land/std`
+```ts
+deno cache --reload=https://deno.land/std@v0.55.0 my_module.ts
+```
 
 To reload specific modules (in this example - colors and file system copy) use a
 comma to separate URLs
 
-`--reload=https://deno.land/std/fs/copy.ts,https://deno.land/std/fmt/colors.ts`
+```ts
+deno cache --reload=https://deno.land/std/fs/copy.ts,https://deno.land/std/fmt/colors.ts my_module.ts
+```
 
 <!-- Should this be part of examples? -->