Made nesting vs inline clearer in the docs.

Also fixed structs not being created inline in the tutorial,
which would actually have bad consequences if used.

Change-Id: Idce215c61a1b24a297cee76f625052bb2722e970

docs/source/Tutorial.md

@@ -798,58 +798,6 @@ elements by calling a lambda. For the common case of `std::vector<std::string>`
 there's also `CreateVectorOfStrings`.
 </div>
 
-To create a `struct`, use the `Vec3` class/struct that was generated by
-the schema compiler:
-
-<div class="language-cpp">
-~~~{.cpp}
-  // Create a `Vec3`, representing the Orc's position in 3-D space.
-  auto pos = Vec3(1.0f, 2.0f, 3.0f);
-~~~
-</div>
-<div class="language-java">
-~~~{.java}
-  // Create a `Vec3`, representing the Orc's position in 3-D space.
-  int pos = Vec3.createVec3(builder, 1.0f, 2.0f, 3.0f);
-~~~
-</div>
-<div class="language-csharp">
-~~~{.cs}
-  // Create a `Vec3`, representing the Orc's position in 3-D space.
-  var pos = Vec3.CreateVec3(builder, 1.0f, 2.0f, 3.0f);
-~~~
-</div>
-<div class="language-go">
-~~~{.go}
-  // Create a `Vec3`, representing the Orc's position in 3-D space.
-  pos := sample.CreateVec3(builder, 1.0, 2.0, 3.0)
-~~~
-</div>
-<div class="language-python">
-~~~{.py}
-  # Create a `Vec3`, representing the Orc's position in 3-D space.
-  pos = MyGame.Sample.Vec3.CreateVec3(builder, 1.0, 2.0, 3.0)
-~~~
-</div>
-<div class="language-javascript">
-~~~{.js}
-  // Create a `Vec3`, representing the Orc's position in 3-D space.
-  var pos = MyGame.Sample.Vec3.createVec3(builder, 1.0, 2.0, 3.0);
-~~~
-</div>
-<div class="language-php">
-~~~{.js}
-  // Create a `Vec3`, representing the Orc's position in 3-D space.
-  $pos = \MyGame\Sample\Vec3::CreateVec3($builder, 1.0, 2.0, 3.0);
-~~~
-</div>
-<div class="language-c">
-~~~{.c}
-  // Create a `Vec3`, representing the Orc's position in 3-D space.
-  ns(Vec3_t) pos = { 1.0f, 2.0f, 3.0f };
-~~~
-</div>
-
 We have now serialized the non-scalar components of the orc, so we
 can serialize the monster itself:
 
@@ -861,15 +809,16 @@ can serialize the monster itself:
 
   // Finally, create the monster using the `CreateMonster` helper function
   // to set all fields.
-  auto orc = CreateMonster(builder, &pos, mana, hp, name, inventory, Color_Red,
-                           weapons, Equipment_Weapon, axe.Union());
+  auto orc = CreateMonster(builder, Vec3(1.0f, 2.0f, 3.0f), mana, hp, name,
+                           inventory, Color_Red, weapons, Equipment_Weapon,
+                           axe.Union());
 ~~~
 </div>
 <div class="language-java">
 ~~~{.java}
   // Create our monster using `startMonster()` and `endMonster()`.
   Monster.startMonster(builder);
-  Monster.addPos(builder, pos);
+  Monster.addPos(builder, Vec3.createVec3(builder, 1.0f, 2.0f, 3.0f));
   Monster.addName(builder, name);
   Monster.addColor(builder, Color.Red);
   Monster.addHp(builder, (short)300);
@@ -884,7 +833,7 @@ can serialize the monster itself:
 ~~~{.cs}
   // Create our monster using `StartMonster()` and `EndMonster()`.
   Monster.StartMonster(builder);
-  Monster.AddPos(builder, pos);
+  Monster.AddPos(builder, Vec3.CreateVec3(builder, 1.0f, 2.0f, 3.0f));
   Monster.AddHp(builder, (short)300);
   Monster.AddName(builder, name);
   Monster.AddInventory(builder, inv);
@@ -899,7 +848,7 @@ can serialize the monster itself:
 ~~~{.go}
   // Create our monster using `MonsterStart()` and `MonsterEnd()`.
   sample.MonsterStart(builder)
-  sample.MonsterAddPos(builder, pos)
+  sample.MonsterAddPos(builder, sample.CreateVec3(builder, 1.0, 2.0, 3.0))
   sample.MonsterAddHp(builder, 300)
   sample.MonsterAddName(builder, name)
   sample.MonsterAddInventory(builder, inv)
@@ -914,7 +863,8 @@ can serialize the monster itself:
 ~~~{.py}
   # Create our monster by using `MonsterStart()` and `MonsterEnd()`.
   MyGame.Sample.Monster.MonsterStart(builder)
-  MyGame.Sample.Monster.MonsterAddPos(builder, pos)
+  MyGame.Sample.Monster.MonsterAddPos(builder,
+                          MyGame.Sample.Vec3.CreateVec3(builder, 1.0, 2.0, 3.0))
   MyGame.Sample.Monster.MonsterAddHp(builder, 300)
   MyGame.Sample.Monster.MonsterAddName(builder, name)
   MyGame.Sample.Monster.MonsterAddInventory(builder, inv)
@@ -931,7 +881,8 @@ can serialize the monster itself:
 ~~~{.js}
   // Create our monster by using `startMonster()` and `endMonster()`.
   MyGame.Sample.Monster.startMonster(builder);
-  MyGame.Sample.Monster.addPos(builder, pos);
+  MyGame.Sample.Monster.addPos(builder,
+                         MyGame.Sample.Vec3.createVec3(builder, 1.0, 2.0, 3.0));
   MyGame.Sample.Monster.addHp(builder, 300);
   MyGame.Sample.Monster.addColor(builder, MyGame.Sample.Color.Red)
   MyGame.Sample.Monster.addName(builder, name);
@@ -946,7 +897,8 @@ can serialize the monster itself:
 ~~~{.php}
   // Create our monster by using `StartMonster()` and `EndMonster()`.
   \MyGame\Sample\Monster::StartMonster($builder);
-  \MyGame\Sample\Monster::AddPos($builder, $pos);
+  \MyGame\Sample\Monster::AddPos($builder,
+                      \MyGame\Sample\Vec3::CreateVec3($builder, 1.0, 2.0, 3.0));
   \MyGame\Sample\Monster::AddHp($builder, 300);
   \MyGame\Sample\Monster::AddName($builder, $name);
   \MyGame\Sample\Monster::AddInventory($builder, $inv);
@@ -966,11 +918,21 @@ can serialize the monster itself:
   // Define an equipment union. `create` calls in C has a single
   // argument for unions where C++ has both a type and a data argument.
   ns(Equipment_union_ref_t) equipped = ns(Equipment_as_Weapon(axe));
+  ns(Vec3_t) pos = { 1.0f, 2.0f, 3.0f };
   ns(Monster_create_as_root(B, &pos, mana, hp, name, inventory, ns(Color_Red),
           weapons, equipped));
 ~~~
 </div>
 
+Note how we create `Vec3` struct in-line in the table. Unlike tables, structs
+are simple combinations of scalars that are always stored inline, just like
+scalars themselves.
+
+**Important**: you should not nest tables or any other objects, which is why
+we created all the strings/vectors/tables that this monster refers to before
+`start`. If you try to create any of them between `start` and `end`, you
+will get an assert/exception/panic depending on your language.
+
 *Note: Since we are passing `150` as the `mana` field, which happens to be the
 default value, the field will not actually be written to the buffer, since the
 default value will be returned on query anyway. This is a nice space savings,