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
diff --git a/docs/source/Tutorial.md b/docs/source/Tutorial.md
index b979064..420524f 100644
--- a/docs/source/Tutorial.md
+++ b/docs/source/Tutorial.md
@@ -798,58 +798,6 @@
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 @@
// 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 @@
~~~{.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 @@
~~~{.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 @@
~~~{.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 @@
~~~{.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 @@
~~~{.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 @@
// 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,
