doc: improve Examples (#7428)

1 files changed, 45 insertions, 27 deletions

diff --git a/docs/examples/import_export.md b/docs/examples/import_export.md
index 37ee8de06..7be14997b 100644
--- a/docs/examples/import_export.md
+++ b/docs/examples/import_export.md
@@ -1,5 +1,17 @@
 # Import and Export Modules
 
+## Concepts
+
+- [import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import)
+  allows you to include and use modules held elsewhere, on your local file
+  system or remotely.
+- Imports are URLs or file system paths
+- [export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export)
+  allows you to specify which parts of your module are accessible to users who
+  import your module
+
+## Overview
+
 Deno by default standardizes the way modules are imported in both JavaScript and
 TypeScript using the ECMAScript 6 `import/export` standard.
 
@@ -27,6 +39,9 @@ In this example the `add` and `multiply` functions are imported from a local
 **Command:** `deno run local.ts`
 
 ```ts
+/**
+ * local.ts
+ */
 import { add, multiply } from "./arithmetic.ts";
 
 function totalCost(outbound: number, inbound: number, tax: number): number {
@@ -44,33 +59,6 @@ console.log(totalCost(45, 27, 1.15));
  */
 ```
 
-## Export
-
-In the example above the `add` and `multiply` functions are imported from a
-locally stored arithmetic module. To make this possible the functions stored in
-the arithmetic module must be exported.
-
-To do this just add the keyword `export` to the beginning of the function
-signature as is shown below.
-
-```ts
-export function add(a: number, b: number): number {
-  return a + b;
-}
-
-export function multiply(a: number, b: number): number {
-  return a * b;
-}
-```
-
-All functions, classes, constants and variables which need to be accessible
-inside external modules must be exported. Either by prepending them with the
-`export` keyword or including them in an export statement at the bottom of the
-file.
-
-To find out more on ECMAScript Export functionality please read the
-[MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export).
-
 ## Remote Import
 
 In the local import example above an `add` and `multiply` method are imported
@@ -84,6 +72,9 @@ no problem handling this.
 **Command:** `deno run ./remote.ts`
 
 ```ts
+/**
+ * remote.ts
+ */
 import {
   add,
   multiply,
@@ -103,3 +94,30 @@ console.log(totalCost(45, 27, 1.15));
  * 82.8
  */
 ```
+
+## Export
+
+In the local import example above the `add` and `multiply` functions are
+imported from a locally stored arithmetic module. To make this possible the
+functions stored in the arithmetic module must be exported.
+
+To do this just add the keyword `export` to the beginning of the function
+signature as is shown below.
+
+```ts
+/**
+ * arithmetic.ts
+ */
+export function add(a: number, b: number): number {
+  return a + b;
+}
+
+export function multiply(a: number, b: number): number {
+  return a * b;
+}
+```
+
+All functions, classes, constants and variables which need to be accessible
+inside external modules must be exported. Either by prepending them with the
+`export` keyword or including them in an export statement at the bottom of the
+file.