diff --git a/packages/winglang/src/commands/test/__snapshots__/test.test.ts.snap b/packages/winglang/src/commands/test/__snapshots__/test.test.ts.snap
index 99106f4b022..44f5295c9c5 100644
--- a/packages/winglang/src/commands/test/__snapshots__/test.test.ts.snap
+++ b/packages/winglang/src/commands/test/__snapshots__/test.test.ts.snap
@@ -1,5 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`printing test reports > results for files with no tests 1`] = `"pass ─ hello.w (no tests)"`;
+
 exports[`printing test reports > verbose traces are not shown if debug mode is disabled 1`] = `
 "fail ┌ hello.w » root/env0/test:test
      │ sleeping for 500 ms
diff --git a/tests/doc_examples/invalid/01-variable-declaration.md_example_1/main.w b/tests/doc_examples/invalid/01-variable-declaration.md_example_1/main.w
deleted file mode 100644
index fe1bf28f255..00000000000
--- a/tests/doc_examples/invalid/01-variable-declaration.md_example_1/main.w
+++ /dev/null
@@ -1,4 +0,0 @@
-// This file was auto generated from an example found in: 01-variable-declaration.md_example_1
-// Example metadata: {"valid":false}
-let x = 12;
-x = 77; // error: Variable is not reassignable
diff --git a/tests/doc_examples/invalid/01-variable-declaration.md_example_4/main.w b/tests/doc_examples/invalid/01-variable-declaration.md_example_4/main.w
deleted file mode 100644
index 1894434fd78..00000000000
--- a/tests/doc_examples/invalid/01-variable-declaration.md_example_4/main.w
+++ /dev/null
@@ -1,9 +0,0 @@
-// This file was auto generated from an example found in: 01-variable-declaration.md_example_4
-// Example metadata: {"valid":false}
-let var x1 = "Hello"; // type str, value "Hello"
-let var x2: str = "Hello"; // same as above 
-let var x3: str? = "Hello"; // type str? (optional), value "Hello"
-let var x4: str? = nil; // type str? (optional), value nil
-
-x1 = nil; // ERROR: Expected type to be "str", but got "nil" instead
-x3 = nil; // OK (x3 is optional)
diff --git a/tests/doc_examples/valid/01-variable-declaration.md_example_2/main.w b/tests/doc_examples/valid/01-variable-declaration.md_example_2/main.w
deleted file mode 100644
index 3ea48d09629..00000000000
--- a/tests/doc_examples/valid/01-variable-declaration.md_example_2/main.w
+++ /dev/null
@@ -1,4 +0,0 @@
-// This file was auto generated from an example found in: 01-variable-declaration.md_example_2
-// Example metadata: {"valid":true}
-let var y = "hello";
-y = "world"; // OK (y is reassignable)
diff --git a/tests/doc_examples/valid/01-variable-declaration.md_example_3/main.w b/tests/doc_examples/valid/01-variable-declaration.md_example_3/main.w
deleted file mode 100644
index d9ef2be947c..00000000000
--- a/tests/doc_examples/valid/01-variable-declaration.md_example_3/main.w
+++ /dev/null
@@ -1,4 +0,0 @@
-// This file was auto generated from an example found in: 01-variable-declaration.md_example_3
-// Example metadata: {"valid":true}
-let x1 = 12; 
-let x2: num = 12; // equivalent 
diff --git a/tests/doc_examples/valid/01-variable-declaration.md_example_5/main.w b/tests/doc_examples/valid/01-variable-declaration.md_example_5/main.w
deleted file mode 100644
index 7b3968d7f14..00000000000
--- a/tests/doc_examples/valid/01-variable-declaration.md_example_5/main.w
+++ /dev/null
@@ -1,9 +0,0 @@
-// This file was auto generated from an example found in: 01-variable-declaration.md_example_5
-// Example metadata: {"valid":true}
-let s = "parent";
-log(s); // prints parent
-if true {
-  let s = "inner";
-  log(s); // prints inner
-}
-log(s); // prints parent
diff --git a/tests/doc_examples/valid/03-functions.md_example_1/main.w b/tests/doc_examples/valid/03-functions.md_example_1/main.w
deleted file mode 100644
index 57ccb08f10b..00000000000
--- a/tests/doc_examples/valid/03-functions.md_example_1/main.w
+++ /dev/null
@@ -1,6 +0,0 @@
-// This file was auto generated from an example found in: 03-functions.md_example_1
-// Example metadata: {"valid":true}
-// preflight function - when declared in preflight context
-let dup = (s: str, count: num) => {
-  // code
-};
diff --git a/tests/doc_examples/valid/02-primitives.md_example_1/main.w b/tests/doc_examples/valid/03-values.md_example_1/main.w
similarity index 78%
rename from tests/doc_examples/valid/02-primitives.md_example_1/main.w
rename to tests/doc_examples/valid/03-values.md_example_1/main.w
index 0cdb9a21d0a..186090ffb55 100644
--- a/tests/doc_examples/valid/02-primitives.md_example_1/main.w
+++ b/tests/doc_examples/valid/03-values.md_example_1/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 02-primitives.md_example_1
+// This file was auto generated from an example found in: 03-values.md_example_1
 // Example metadata: {"valid":true}
 let s1 = "Hello Wing String";
 log(s1); // prints Hello Wing String
diff --git a/tests/doc_examples/valid/02-primitives.md_example_2/main.w b/tests/doc_examples/valid/03-values.md_example_2/main.w
similarity index 87%
rename from tests/doc_examples/valid/02-primitives.md_example_2/main.w
rename to tests/doc_examples/valid/03-values.md_example_2/main.w
index 5535f0a4670..563bf0d177c 100644
--- a/tests/doc_examples/valid/02-primitives.md_example_2/main.w
+++ b/tests/doc_examples/valid/03-values.md_example_2/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 02-primitives.md_example_2
+// This file was auto generated from an example found in: 03-values.md_example_2
 // Example metadata: {"valid":true}
 let s = "Hello to a new Wing world";
 
diff --git a/tests/doc_examples/valid/02-primitives.md_example_3/main.w b/tests/doc_examples/valid/03-values.md_example_3/main.w
similarity index 82%
rename from tests/doc_examples/valid/02-primitives.md_example_3/main.w
rename to tests/doc_examples/valid/03-values.md_example_3/main.w
index b8d9fe60c56..1885cb0c886 100644
--- a/tests/doc_examples/valid/02-primitives.md_example_3/main.w
+++ b/tests/doc_examples/valid/03-values.md_example_3/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 02-primitives.md_example_3
+// This file was auto generated from an example found in: 03-values.md_example_3
 // Example metadata: {"valid":true}
 let n1 = 10;
 log("{n1}"); // 10
diff --git a/tests/doc_examples/valid/02-primitives.md_example_4/main.w b/tests/doc_examples/valid/03-values.md_example_4/main.w
similarity index 62%
rename from tests/doc_examples/valid/02-primitives.md_example_4/main.w
rename to tests/doc_examples/valid/03-values.md_example_4/main.w
index c9dbf43d252..904472ebaed 100644
--- a/tests/doc_examples/valid/02-primitives.md_example_4/main.w
+++ b/tests/doc_examples/valid/03-values.md_example_4/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 02-primitives.md_example_4
+// This file was auto generated from an example found in: 03-values.md_example_4
 // Example metadata: {"valid":true}
 let b1 = true;
 let b2 = false;
diff --git a/tests/doc_examples/valid/04-flow-controls.md_example_1/main.w b/tests/doc_examples/valid/04-flow-controls.md_example_1/main.w
deleted file mode 100644
index 94383efc82b..00000000000
--- a/tests/doc_examples/valid/04-flow-controls.md_example_1/main.w
+++ /dev/null
@@ -1,22 +0,0 @@
-// This file was auto generated from an example found in: 04-flow-controls.md_example_1
-// Example metadata: {"valid":true}
-let iterable = ["a", "b", "c", "d", "e", "f", "g", "h"];
-for value in iterable {
-  if value == "g" {
-    // stopping at g
-    break;
-  }
-  if value == "b" {
-    // skipping b
-    continue;
-  }
-  log(value);
-}
-/** 
- * prints
- a
- c
- d
- e
- f
-**/
diff --git a/tests/doc_examples/valid/04-flow-controls.md_example_2/main.w b/tests/doc_examples/valid/04-flow-controls.md_example_2/main.w
deleted file mode 100644
index 9b83cbcd9bc..00000000000
--- a/tests/doc_examples/valid/04-flow-controls.md_example_2/main.w
+++ /dev/null
@@ -1,16 +0,0 @@
-// This file was auto generated from an example found in: 04-flow-controls.md_example_2
-// Example metadata: {"valid":true}
-// print numbers from 0 to 9
-for value in 0..10 {
-  log("{value}");
-}
-
-// prints numbers in reverse order from 10 to 0
-for value in 10..-1 {
-    log("{value}");
-}
-
-// include end
-for value in 1..=5 {
-    log("{value}");
-}
diff --git a/tests/doc_examples/valid/04-flow-controls.md_example_3/main.w b/tests/doc_examples/valid/04-flow-controls.md_example_3/main.w
deleted file mode 100644
index 3921f02001a..00000000000
--- a/tests/doc_examples/valid/04-flow-controls.md_example_3/main.w
+++ /dev/null
@@ -1,23 +0,0 @@
-// This file was auto generated from an example found in: 04-flow-controls.md_example_3
-// Example metadata: {"valid":true}
-let grade = (score: num): str => {
-    // Parentheses are optional in conditions.
-    // However, curly braces are required in `if/else` statements.
-    if 0 < score && score < 55 {
-        return "F";
-    } else if 55 <= score && score < 65 {
-        return "C";
-    } else if 65 <= score && score < 75  {
-        return "B";
-    } else if 75 <= score && score <= 100 {
-        return "A";
-    } else {
-        return "Invalid grade";
-    }
-};
-
-log("54 is {grade(54)}"); // 54 is F
-log("62 is {grade(62)}"); // 62 is C
-log("68 is {grade(68)}"); // 68 is B
-log("99 is {grade(99)}"); // 99 is A
-log("101 is {grade(101)}"); // 101 is Invalid grade
diff --git a/tests/doc_examples/valid/04-flow-controls.md_example_4/main.w b/tests/doc_examples/valid/04-flow-controls.md_example_4/main.w
deleted file mode 100644
index b6e84150263..00000000000
--- a/tests/doc_examples/valid/04-flow-controls.md_example_4/main.w
+++ /dev/null
@@ -1,28 +0,0 @@
-// This file was auto generated from an example found in: 04-flow-controls.md_example_4
-// Example metadata: {"valid":true}
-let var i = 0;
-while i < 100 {
-  i = i + 1;
-  if i == 20 {
-    // although the while loop goes to 100, we break it at 20
-    break;
-  }
-  if i % 2 == 0 {
-    // continue for even numbers
-    continue;
-  }
-  log("{i}");
-}
-/** 
- * prints
-  1
-  3
-  5
-  7
-  9
-  11
-  13
-  15
-  17
-  19
-**/
diff --git a/tests/doc_examples/valid/05-optionality.md_example_1/main.w b/tests/doc_examples/valid/05-optionality.md_example_1/main.w
deleted file mode 100644
index 99c37bc9059..00000000000
--- a/tests/doc_examples/valid/05-optionality.md_example_1/main.w
+++ /dev/null
@@ -1,4 +0,0 @@
-// This file was auto generated from an example found in: 05-optionality.md_example_1
-// Example metadata: {"valid":true}
-let s1: str? = "Hello"; // type str? (optional), value "Hello"
-let s2: str? = nil; // type str? (optional), value nil
diff --git a/tests/doc_examples/valid/06-json.md_example_1/main.w b/tests/doc_examples/valid/06-json.md_example_1/main.w
deleted file mode 100644
index 033b7e26cd3..00000000000
--- a/tests/doc_examples/valid/06-json.md_example_1/main.w
+++ /dev/null
@@ -1,23 +0,0 @@
-// This file was auto generated from an example found in: 06-json.md_example_1
-// Example metadata: {"valid":true}
-let j = Json {
-  k1: 1,
-  k2: "hello",
-  k3: true,
-  k4: {
-    k1: [1, "a", true, {} ]
-  }
-};
-log("{j}");
-
-let jsonStrValue = Json "Hello";
-log("{jsonStrValue}");
-
-let jsonNumValue = Json 42;
-log("{jsonNumValue}");
-
-let jsonBoolValue = Json true;
-log("{jsonBoolValue}");
-
-let jsonHomogeneousArrayValue = Json ["a", "b"];
-log("{jsonHomogeneousArrayValue}");
diff --git a/tests/doc_examples/valid/07-structs.md_example_1/main.w b/tests/doc_examples/valid/07-structs.md_example_1/main.w
deleted file mode 100644
index ac77a1892a0..00000000000
--- a/tests/doc_examples/valid/07-structs.md_example_1/main.w
+++ /dev/null
@@ -1,10 +0,0 @@
-// This file was auto generated from an example found in: 07-structs.md_example_1
-// Example metadata: {"valid":true}
-struct Example {
-  a: str;
-  b: num;
-  c: bool;
-}
-
-let example = Example { a: "a", b: 0, c: false };
-log(example.a); // prints "a"
diff --git a/tests/doc_examples/valid/07-structs.md_example_2/main.w b/tests/doc_examples/valid/07-structs.md_example_2/main.w
deleted file mode 100644
index c54e3b5bb80..00000000000
--- a/tests/doc_examples/valid/07-structs.md_example_2/main.w
+++ /dev/null
@@ -1,12 +0,0 @@
-// This file was auto generated from an example found in: 07-structs.md_example_2
-// Example metadata: {"valid":true}
-struct Example {
-  a: str?;
-  b: num?;
-  c: bool?;
-}
-
-let example = Example { };
-if example.a == nil {
-  log("a is nil"); 
-}
diff --git a/tests/doc_examples/valid/07-structs.md_example_3/main.w b/tests/doc_examples/valid/07-structs.md_example_3/main.w
deleted file mode 100644
index 97b1088b98b..00000000000
--- a/tests/doc_examples/valid/07-structs.md_example_3/main.w
+++ /dev/null
@@ -1,21 +0,0 @@
-// This file was auto generated from an example found in: 07-structs.md_example_3
-// Example metadata: {"valid":true}
-struct Another {
-  hello: str;
-}
-
-struct MyData {
-  a: str;
-  b: num?;
-  c: Another;
-}
-
-let data = MyData {
-  a: "hello",
-  c: Another {
-    hello: "two"
-  }
-};
-
-log(data.a); // prints hello  
-log(data.c.hello); // prints two
diff --git a/tests/doc_examples/valid/07-structs.md_example_4/main.w b/tests/doc_examples/valid/07-structs.md_example_4/main.w
deleted file mode 100644
index 54867719c4c..00000000000
--- a/tests/doc_examples/valid/07-structs.md_example_4/main.w
+++ /dev/null
@@ -1,17 +0,0 @@
-// This file was auto generated from an example found in: 07-structs.md_example_4
-// Example metadata: {"valid":true}
-struct Options {
-  prefix: str?;
-  delim: str;
-}
-
-let join_str = (a: Array<str>, opts: Options):str => {
-  let prefix = opts.prefix ?? "";
-  return prefix + a.join(opts.delim);
-};
-
-log(join_str(["hello", "world"], delim: ", ")); //  "!hello.world"
-
-// also OK to pass an object
-let opts = Options { delim: "," };
-log(join_str(["hello", "world"], opts)); // "!!hello/world");
diff --git a/tests/doc_examples/valid/08-classes.md_example_4/main.w b/tests/doc_examples/valid/08-classes.md_example_4/main.w
deleted file mode 100644
index c3ad7f6f634..00000000000
--- a/tests/doc_examples/valid/08-classes.md_example_4/main.w
+++ /dev/null
@@ -1,32 +0,0 @@
-// This file was auto generated from an example found in: 08-classes.md_example_4
-// Example metadata: {"valid":true}
-bring cloud;
-
-interface IKVStore extends std.IResource { 
-  inflight get(key: str): Json;
-  inflight set(key: str, value: Json): void;
-}
-
-class BucketBasedKeyValueStore impl IKVStore {
-  bucket: cloud.Bucket;
-  new() {
-    this.bucket = new cloud.Bucket();
-  }
-  pub inflight get(key: str): Json {
-    return this.bucket.getJson(key);
-  }
-  pub inflight set(key: str, value: Json): void {
-    this.bucket.putJson(key, value);
-  }
-}
-
-let bucketBased: IKVStore = new BucketBasedKeyValueStore();
-
-test "bucketBased KVStore" {
-  bucketBased.set("k", Json {
-    value: "v"
-  });
-  let result = bucketBased.get("k");
-  log("{result.get("value")}");
-  assert("v" == str.fromJson(result.get("value")));
-}
diff --git a/tests/doc_examples/valid/05-optionality.md_example_2/main.w b/tests/doc_examples/valid/08-optionality.md_example_1/main.w
similarity index 73%
rename from tests/doc_examples/valid/05-optionality.md_example_2/main.w
rename to tests/doc_examples/valid/08-optionality.md_example_1/main.w
index 32e7b01cca6..08a135a455c 100644
--- a/tests/doc_examples/valid/05-optionality.md_example_2/main.w
+++ b/tests/doc_examples/valid/08-optionality.md_example_1/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 05-optionality.md_example_2
+// This file was auto generated from an example found in: 08-optionality.md_example_1
 // Example metadata: {"valid":true}
 let s1: str? = "Hello"; // type str? (optional), value "Hello"
 let s2: str? = nil; // type str? (optional), value nil
diff --git a/tests/doc_examples/valid/05-optionality.md_example_3/main.w b/tests/doc_examples/valid/08-optionality.md_example_2/main.w
similarity index 83%
rename from tests/doc_examples/valid/05-optionality.md_example_3/main.w
rename to tests/doc_examples/valid/08-optionality.md_example_2/main.w
index e4355080865..c35daeaa4ec 100644
--- a/tests/doc_examples/valid/05-optionality.md_example_3/main.w
+++ b/tests/doc_examples/valid/08-optionality.md_example_2/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 05-optionality.md_example_3
+// This file was auto generated from an example found in: 08-optionality.md_example_2
 // Example metadata: {"valid":true}
 let s1: str? = "Hello"; // type str? (optional), value "Hello"
 
diff --git a/tests/doc_examples/valid/05-optionality.md_example_4/main.w b/tests/doc_examples/valid/08-optionality.md_example_3/main.w
similarity index 67%
rename from tests/doc_examples/valid/05-optionality.md_example_4/main.w
rename to tests/doc_examples/valid/08-optionality.md_example_3/main.w
index f9589cfb47b..03a5937d1dc 100644
--- a/tests/doc_examples/valid/05-optionality.md_example_4/main.w
+++ b/tests/doc_examples/valid/08-optionality.md_example_3/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 05-optionality.md_example_4
+// This file was auto generated from an example found in: 08-optionality.md_example_3
 // Example metadata: {"valid":true}
 let s1: str? = nil; // type str? (optional), value nil
 let s2 = s1 ?? "default value";  // s2 is of type str
diff --git a/tests/doc_examples/valid/05-optionality.md_example_5/main.w b/tests/doc_examples/valid/08-optionality.md_example_4/main.w
similarity index 80%
rename from tests/doc_examples/valid/05-optionality.md_example_5/main.w
rename to tests/doc_examples/valid/08-optionality.md_example_4/main.w
index 1f906eb049c..be66cd87ace 100644
--- a/tests/doc_examples/valid/05-optionality.md_example_5/main.w
+++ b/tests/doc_examples/valid/08-optionality.md_example_4/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 05-optionality.md_example_5
+// This file was auto generated from an example found in: 08-optionality.md_example_4
 // Example metadata: {"valid":true}
 let j  = Json {
   working: {
diff --git a/tests/doc_examples/valid/05-optionality.md_example_6/main.w b/tests/doc_examples/valid/08-optionality.md_example_5/main.w
similarity index 75%
rename from tests/doc_examples/valid/05-optionality.md_example_6/main.w
rename to tests/doc_examples/valid/08-optionality.md_example_5/main.w
index 803e8ef0cd9..5685f22f620 100644
--- a/tests/doc_examples/valid/05-optionality.md_example_6/main.w
+++ b/tests/doc_examples/valid/08-optionality.md_example_5/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 05-optionality.md_example_6
+// This file was auto generated from an example found in: 08-optionality.md_example_5
 // Example metadata: {"valid":true}
 let b3: bool? = false; 
 
diff --git a/tests/doc_examples/valid/12-structs.md_example_1/main.w b/tests/doc_examples/valid/12-structs.md_example_1/main.w
index b158780d0de..dbf60e44bc6 100644
--- a/tests/doc_examples/valid/12-structs.md_example_1/main.w
+++ b/tests/doc_examples/valid/12-structs.md_example_1/main.w
@@ -23,6 +23,6 @@ let data = MyData {
   }
 };
 
-log(data.a);        
-log(data.c.a);      
-log(data.c.b);      
+log(data.a); // prints hello    
+log(data.c.a); //prints world
+log(data.c.b); //prints 42
diff --git a/tests/doc_examples/valid/03-functions.md_example_3/main.w b/tests/doc_examples/valid/12-structs.md_example_2/main.w
similarity index 64%
rename from tests/doc_examples/valid/03-functions.md_example_3/main.w
rename to tests/doc_examples/valid/12-structs.md_example_2/main.w
index 4b7db9fa5c9..2e382346af2 100644
--- a/tests/doc_examples/valid/03-functions.md_example_3/main.w
+++ b/tests/doc_examples/valid/12-structs.md_example_2/main.w
@@ -1,7 +1,9 @@
-// This file was auto generated from an example found in: 03-functions.md_example_3
+// This file was auto generated from an example found in: 12-structs.md_example_2
 // Example metadata: {"valid":true}
 struct Options {
+  // optional
   prefix: str?;
+  // required
   delim: str;
 }
 
@@ -10,7 +12,8 @@ let join_str = (a: Array<str>, opts: Options):str => {
   return prefix + a.join(opts.delim);
 };
 
-log(join_str(["hello", "world"], delim: ", ")); //  "!hello.world"
+// pass options directly
+log(join_str(["hello", "world"], delim: ", ")); //  "hello, world"
 
 // also OK to pass an object
 let opts = Options { delim: "/" , prefix: "!!" };
diff --git a/tests/doc_examples/valid/14-functions.md_example_1/main.w b/tests/doc_examples/valid/14-functions.md_example_1/main.w
index eef40b0312d..519563e4e4d 100644
--- a/tests/doc_examples/valid/14-functions.md_example_1/main.w
+++ b/tests/doc_examples/valid/14-functions.md_example_1/main.w
@@ -15,4 +15,4 @@ let func = new cloud.Function(inflight (payload:Json?) => {
 
 let value = plus(1, 2);
 
-log(value);
+log(value); // 3
diff --git a/tests/doc_examples/valid/03-functions.md_example_2/main.w b/tests/doc_examples/valid/14-functions.md_example_2/main.w
similarity index 84%
rename from tests/doc_examples/valid/03-functions.md_example_2/main.w
rename to tests/doc_examples/valid/14-functions.md_example_2/main.w
index a7ca33ea8a9..e2eb3aa902e 100644
--- a/tests/doc_examples/valid/03-functions.md_example_2/main.w
+++ b/tests/doc_examples/valid/14-functions.md_example_2/main.w
@@ -1,6 +1,5 @@
-// This file was auto generated from an example found in: 03-functions.md_example_2
+// This file was auto generated from an example found in: 14-functions.md_example_2
 // Example metadata: {"valid":true}
-
 let handler = inflight (message: str): void => {
   // using the inflight modifier 
   let dup = inflight (s: str, count: num) => {
diff --git a/tests/doc_examples/valid/15-variadic-functions.md_example_1/main.w b/tests/doc_examples/valid/14-variadic-functions.md_example_1/main.w
similarity index 86%
rename from tests/doc_examples/valid/15-variadic-functions.md_example_1/main.w
rename to tests/doc_examples/valid/14-variadic-functions.md_example_1/main.w
index 494d86a6635..e5337547f7d 100644
--- a/tests/doc_examples/valid/15-variadic-functions.md_example_1/main.w
+++ b/tests/doc_examples/valid/14-variadic-functions.md_example_1/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 15-variadic-functions.md_example_1
+// This file was auto generated from an example found in: 14-variadic-functions.md_example_1
 // Example metadata: {"valid":true}
 // Function that will take an arbitrary number of numbers as arguments.
 let plus = (...numbers: Array<num>) => {
diff --git a/tests/doc_examples/valid/08-classes.md_example_1/main.w b/tests/doc_examples/valid/15-classes.md_example_1/main.w
similarity index 67%
rename from tests/doc_examples/valid/08-classes.md_example_1/main.w
rename to tests/doc_examples/valid/15-classes.md_example_1/main.w
index 4dcab81f940..50b4719710f 100644
--- a/tests/doc_examples/valid/08-classes.md_example_1/main.w
+++ b/tests/doc_examples/valid/15-classes.md_example_1/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 08-classes.md_example_1
+// This file was auto generated from an example found in: 15-classes.md_example_1
 // Example metadata: {"valid":true}
 bring cloud;
 bring util;
@@ -17,11 +17,13 @@ class Foo  {
     this.field2 = value;
   }
 
+  // private inflight function, only accessible during inflight
   inflight new() {
     this.field3 = ["value created on inflight init"];
     log("at inflight init");
   }
 
+  // public inflight function, only accessible during inflight
   pub inflight doStuff() {
     // all code is async and runs on the cloud
     log("field3[0]='{this.field3.at(0)}'");
@@ -34,7 +36,10 @@ let f = new Foo();
 log("field1={f.field1}");
 log("field2={f.field2}");
 
+// inflight example for a cloud function
 new cloud.Function(inflight () => {
+  // calling the public inflight function (doStuff) of the Foo class.
+  // This function is not accessible during preflight.
   f.doStuff();
 });
 
diff --git a/tests/doc_examples/valid/08-classes.md_example_2/main.w b/tests/doc_examples/valid/15-classes.md_example_2/main.w
similarity index 60%
rename from tests/doc_examples/valid/08-classes.md_example_2/main.w
rename to tests/doc_examples/valid/15-classes.md_example_2/main.w
index 2d3401ba798..8ba5246950f 100644
--- a/tests/doc_examples/valid/08-classes.md_example_2/main.w
+++ b/tests/doc_examples/valid/15-classes.md_example_2/main.w
@@ -1,17 +1,22 @@
-// This file was auto generated from an example found in: 08-classes.md_example_2
+// This file was auto generated from an example found in: 15-classes.md_example_2
 // Example metadata: {"valid":true}
 bring cloud;
 
+// define the interface
 inflight interface IProfile {
+  // inflight function
   inflight name(): str;
 }
 
+// new class that implements the interface
 inflight class WingPerson impl IProfile {
+  // custom definition of the name function
   pub inflight name(): str {
     return "Fairy Wing";
   }
 }
 
+// inflight function that accepts the interface
 let logName = inflight(profile: IProfile): void => {
   log(profile.name());
 };
diff --git a/tests/doc_examples/valid/08-classes.md_example_3/main.w b/tests/doc_examples/valid/15-classes.md_example_3/main.w
similarity index 89%
rename from tests/doc_examples/valid/08-classes.md_example_3/main.w
rename to tests/doc_examples/valid/15-classes.md_example_3/main.w
index f84b999927f..a563d31a2e7 100644
--- a/tests/doc_examples/valid/08-classes.md_example_3/main.w
+++ b/tests/doc_examples/valid/15-classes.md_example_3/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 08-classes.md_example_3
+// This file was auto generated from an example found in: 15-classes.md_example_3
 // Example metadata: {"valid":true}
 bring cloud;
 /**
diff --git a/tests/doc_examples/valid/14-singletons.md_example_1/main.w b/tests/doc_examples/valid/15-singletons.md_example_1/main.w
similarity index 84%
rename from tests/doc_examples/valid/14-singletons.md_example_1/main.w
rename to tests/doc_examples/valid/15-singletons.md_example_1/main.w
index e153693bfa8..976dfcc9eda 100644
--- a/tests/doc_examples/valid/14-singletons.md_example_1/main.w
+++ b/tests/doc_examples/valid/15-singletons.md_example_1/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 14-singletons.md_example_1
+// This file was auto generated from an example found in: 15-singletons.md_example_1
 // Example metadata: {"valid":true}
 bring cloud;
 
diff --git a/tests/doc_examples/valid/23-Json.md_example_1/main.w b/tests/doc_examples/valid/23-Json.md_example_1/main.w
index 3bc8941ed85..fcf18a6277f 100644
--- a/tests/doc_examples/valid/23-Json.md_example_1/main.w
+++ b/tests/doc_examples/valid/23-Json.md_example_1/main.w
@@ -6,49 +6,20 @@ let person = Json {
 };
 
 // stringify
-log(Json.stringify(person));
+log(Json.stringify(person)); // {"firstName":"John","lastName":"Smith"}
 
 // parse 
-log(Json.parse("\{\"firstName\":\"John\",\"lastName\":\"Smith\"}"));
+log(Json.parse("\{\"firstName\":\"John\",\"lastName\":\"Smith\"}")); // { firstName: 'John', lastName: 'Smith' }
 
 // Try and parse
 if let jsonFromTryParse = Json.tryParse("\{\"firstName\":\"John\",\"lastName\":\"Smith\"}") {
-  log("{jsonFromTryParse}");
+  log("{jsonFromTryParse}"); // {"firstName":"John","lastName":"Smith"}
 } else {
   log("failed to parse string to JSON");
 }
 
 // Deep copy of Json
 let newPerson = Json.deepCopy(person);
-log(Json.stringify(person));
+log(Json.stringify(person)); // {"firstName":"John","lastName":"Smith"}
 
-// iterate over keys
-for k in Json.keys(person) {
-  let value = person.get(k);
-  log("found key {k} with value {value}");
-}
-
-// iterate over values
-for value in Json.values(person) {
-  log("found value {value}");
-}
-
-// iterate over array
-let arrayValue = Json ["a", "b", "c"];
-for v in Json.values(arrayValue) {
-  log(str.fromJson(v));
-}
-
-// Convert to structs
-struct Foo {
-  val1: str;
-  val2: num;
-}
-
-let jFoo = {
-  val1: "cool",
-  val2: 21
-};
 
-let foo = Foo.fromJson(jFoo);
-log(Json.stringify(foo));
diff --git a/tests/doc_examples/valid/06-json.md_example_9/main.w b/tests/doc_examples/valid/23-Json.md_example_10/main.w
similarity index 65%
rename from tests/doc_examples/valid/06-json.md_example_9/main.w
rename to tests/doc_examples/valid/23-Json.md_example_10/main.w
index 1e35a7912f0..d20260260de 100644
--- a/tests/doc_examples/valid/06-json.md_example_9/main.w
+++ b/tests/doc_examples/valid/23-Json.md_example_10/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 06-json.md_example_9
+// This file was auto generated from an example found in: 23-Json.md_example_10
 // Example metadata: {"valid":true}
 struct Foo {
   val1: str;
diff --git a/tests/doc_examples/valid/23-Json.md_example_2/main.w b/tests/doc_examples/valid/23-Json.md_example_2/main.w
new file mode 100644
index 00000000000..1e2f47cbfe1
--- /dev/null
+++ b/tests/doc_examples/valid/23-Json.md_example_2/main.w
@@ -0,0 +1,23 @@
+// This file was auto generated from an example found in: 23-Json.md_example_2
+// Example metadata: {"valid":true}
+let j = Json {
+  k1: 1,
+  k2: "hello",
+  k3: true,
+  k4: {
+    k1: [1, "a", true, {} ]
+  }
+};
+log("{j}"); // {"k1":1,"k2":"hello","k3":true,"k4":{"k1":[1,"a",true,{}]}}
+
+let jsonStrValue = Json "Hello";
+log("{jsonStrValue}"); // "Hello"
+
+let jsonNumValue = Json 42;
+log("{jsonNumValue}"); // 42
+
+let jsonBoolValue = Json true;
+log("{jsonBoolValue}"); // true 
+
+let jsonHomogeneousArrayValue = Json ["a", "b"];
+log("{jsonHomogeneousArrayValue}"); // ["a","b"]
diff --git a/tests/doc_examples/valid/06-json.md_example_2/main.w b/tests/doc_examples/valid/23-Json.md_example_3/main.w
similarity index 79%
rename from tests/doc_examples/valid/06-json.md_example_2/main.w
rename to tests/doc_examples/valid/23-Json.md_example_3/main.w
index 82418742392..7bbf71ad6e8 100644
--- a/tests/doc_examples/valid/06-json.md_example_2/main.w
+++ b/tests/doc_examples/valid/23-Json.md_example_3/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 06-json.md_example_2
+// This file was auto generated from an example found in: 23-Json.md_example_3
 // Example metadata: {"valid":true}
 let x: num = 42;
 let jsonNum = Json x;
diff --git a/tests/doc_examples/valid/06-json.md_example_3/main.w b/tests/doc_examples/valid/23-Json.md_example_4/main.w
similarity index 68%
rename from tests/doc_examples/valid/06-json.md_example_3/main.w
rename to tests/doc_examples/valid/23-Json.md_example_4/main.w
index 04a1ca743aa..acebe10cfb1 100644
--- a/tests/doc_examples/valid/06-json.md_example_3/main.w
+++ b/tests/doc_examples/valid/23-Json.md_example_4/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 06-json.md_example_3
+// This file was auto generated from an example found in: 23-Json.md_example_4
 // Example metadata: {"valid":true}
 let j = Json {
     k1: "v1",
diff --git a/tests/doc_examples/valid/06-json.md_example_4/main.w b/tests/doc_examples/valid/23-Json.md_example_5/main.w
similarity index 64%
rename from tests/doc_examples/valid/06-json.md_example_4/main.w
rename to tests/doc_examples/valid/23-Json.md_example_5/main.w
index 9d51fe48328..a61418b92ec 100644
--- a/tests/doc_examples/valid/06-json.md_example_4/main.w
+++ b/tests/doc_examples/valid/23-Json.md_example_5/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 06-json.md_example_4
+// This file was auto generated from an example found in: 23-Json.md_example_5
 // Example metadata: {"valid":true}
 let j = Json {
     k1: "v1",
diff --git a/tests/doc_examples/valid/06-json.md_example_5/main.w b/tests/doc_examples/valid/23-Json.md_example_6/main.w
similarity index 63%
rename from tests/doc_examples/valid/06-json.md_example_5/main.w
rename to tests/doc_examples/valid/23-Json.md_example_6/main.w
index f677769b9fa..4178b8ef3d8 100644
--- a/tests/doc_examples/valid/06-json.md_example_5/main.w
+++ b/tests/doc_examples/valid/23-Json.md_example_6/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 06-json.md_example_5
+// This file was auto generated from an example found in: 23-Json.md_example_6
 // Example metadata: {"valid":true}
 let arrayValue = Json ["a", "b", "c"];
 for v in Json.values(arrayValue) {
diff --git a/tests/doc_examples/valid/06-json.md_example_6/main.w b/tests/doc_examples/valid/23-Json.md_example_7/main.w
similarity index 54%
rename from tests/doc_examples/valid/06-json.md_example_6/main.w
rename to tests/doc_examples/valid/23-Json.md_example_7/main.w
index b83d75c0243..7ccb4aab170 100644
--- a/tests/doc_examples/valid/06-json.md_example_6/main.w
+++ b/tests/doc_examples/valid/23-Json.md_example_7/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 06-json.md_example_6
+// This file was auto generated from an example found in: 23-Json.md_example_7
 // Example metadata: {"valid":true}
 let j = Json {
     k: "hello"
diff --git a/tests/doc_examples/valid/06-json.md_example_7/main.w b/tests/doc_examples/valid/23-Json.md_example_8/main.w
similarity index 53%
rename from tests/doc_examples/valid/06-json.md_example_7/main.w
rename to tests/doc_examples/valid/23-Json.md_example_8/main.w
index 20547f84dbc..d5efa3639c6 100644
--- a/tests/doc_examples/valid/06-json.md_example_7/main.w
+++ b/tests/doc_examples/valid/23-Json.md_example_8/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 06-json.md_example_7
+// This file was auto generated from an example found in: 23-Json.md_example_8
 // Example metadata: {"valid":true}
 let j = Json {
   k: 12
diff --git a/tests/doc_examples/valid/06-json.md_example_8/main.w b/tests/doc_examples/valid/23-Json.md_example_9/main.w
similarity index 54%
rename from tests/doc_examples/valid/06-json.md_example_8/main.w
rename to tests/doc_examples/valid/23-Json.md_example_9/main.w
index c1fe2966aef..3694d8f62f2 100644
--- a/tests/doc_examples/valid/06-json.md_example_8/main.w
+++ b/tests/doc_examples/valid/23-Json.md_example_9/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 06-json.md_example_8
+// This file was auto generated from an example found in: 23-Json.md_example_9
 // Example metadata: {"valid":true}
 let j = Json {
   k:true
diff --git a/tests/doc_examples/valid/13-api-gateway.md_example_1/main.w b/tests/doc_examples/valid/34-http-server.md_example_2/main.w
similarity index 89%
rename from tests/doc_examples/valid/13-api-gateway.md_example_1/main.w
rename to tests/doc_examples/valid/34-http-server.md_example_2/main.w
index 7fb3c783d3a..3739b0492a8 100644
--- a/tests/doc_examples/valid/13-api-gateway.md_example_1/main.w
+++ b/tests/doc_examples/valid/34-http-server.md_example_2/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 13-api-gateway.md_example_1
+// This file was auto generated from an example found in: 34-http-server.md_example_2
 // Example metadata: {"valid":true}
 bring cloud;
 
diff --git a/tests/doc_examples/valid/13-api-gateway.md_example_2/main.w b/tests/doc_examples/valid/34-http-server.md_example_3/main.w
similarity index 82%
rename from tests/doc_examples/valid/13-api-gateway.md_example_2/main.w
rename to tests/doc_examples/valid/34-http-server.md_example_3/main.w
index c4fbe45e598..985f31326f9 100644
--- a/tests/doc_examples/valid/13-api-gateway.md_example_2/main.w
+++ b/tests/doc_examples/valid/34-http-server.md_example_3/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 13-api-gateway.md_example_2
+// This file was auto generated from an example found in: 34-http-server.md_example_3
 // Example metadata: {"valid":true}
 bring cloud;
 
diff --git a/tests/doc_examples/valid/13-api-gateway.md_example_3/main.w b/tests/doc_examples/valid/34-http-server.md_example_4/main.w
similarity index 84%
rename from tests/doc_examples/valid/13-api-gateway.md_example_3/main.w
rename to tests/doc_examples/valid/34-http-server.md_example_4/main.w
index 1615f1620e9..5cb2d8d2486 100644
--- a/tests/doc_examples/valid/13-api-gateway.md_example_3/main.w
+++ b/tests/doc_examples/valid/34-http-server.md_example_4/main.w
@@ -1,4 +1,4 @@
-// This file was auto generated from an example found in: 13-api-gateway.md_example_3
+// This file was auto generated from an example found in: 34-http-server.md_example_4
 // Example metadata: {"valid":true}
 bring cloud;
 
diff --git a/tests/doc_examples/valid/37-duration.md_example_1/main.w b/tests/doc_examples/valid/37-duration.md_example_1/main.w
new file mode 100644
index 00000000000..a723fd8b089
--- /dev/null
+++ b/tests/doc_examples/valid/37-duration.md_example_1/main.w
@@ -0,0 +1,19 @@
+// This file was auto generated from an example found in: 37-duration.md_example_1
+// Example metadata: {"valid":true}
+let msInHour = duration.fromHours(1).milliseconds;
+let msInSeconds = duration.fromSeconds(30).milliseconds;
+let secondsInDay = duration.fromDays(1).seconds;
+let hoursInDay = duration.fromDays(1).hours;
+let hoursInMonth = duration.fromMonths(1).hours;
+let daysInYear = duration.fromYears(1).days;
+
+let durations = {
+  msInHour,
+  msInSeconds,
+  secondsInDay,
+  hoursInDay,
+  hoursInMonth,
+  daysInYear
+};
+
+log(Json.stringify(durations));