Various documentation improvements.

Change-Id: Iacea45ae0f602f49e46de472286a7a77ee20c301

docs/source/GoUsage.md

@@ -75,7 +75,8 @@ Unlike C++, Go does not support table creation functions like 'createMonster()'.
 This is to create the buffer without
 using temporary object allocation (since the `Vec3` is an inline component of
 `Monster`, it has to be created right where it is added, whereas the name and
-the inventory are not inline).
+the inventory are not inline, and **must** be created outside of the table
+creation sequence).
 Structs do have convenient methods that allow you to construct them in one call.
 These also have arguments for nested structs, e.g. if a struct has a field `a`
 and a nested struct field `b` (which has fields `c` and `d`), then the arguments
@@ -97,13 +98,22 @@ function which calls 'StartVector' with the correct element size of the vector
 type which in this case is 'ubyte' or 1 byte per vector element.
 You pass the number of elements you want to write.
 You write the elements backwards since the buffer
-is being constructed back to front.
+is being constructed back to front. You then pass `inv` to the corresponding
+`Add` call when you construct the table containing it afterwards.
 
 There are `Prepend` functions for all the scalar types. You use
 `PrependUOffset` for any previously constructed objects (such as other tables,
 strings, vectors). For structs, you use the appropriate `create` function
 in-line, as shown above in the `Monster` example.
 
+Once you're done constructing a buffer, you call `Finish` with the root object
+offset (`mon` in the example above). Your data now resides in Builder.Bytes.
+Important to note is that the real data starts at the index indicated by Head(),
+for Offset() bytes (this is because the buffer is constructed backwards).
+If you wanted to read the buffer right after creating it (using
+`GetRootAsMonster` above), the second argument, instead of `0` would thus
+also be `Head()`.
+
 ## Text Parsing
 
 There currently is no support for parsing text (Schema's and JSON) directly

docs/source/JavaUsage.md

@@ -125,7 +125,8 @@ does not sit in an array, you can also use the start/end pattern:
 You can use the generated method `startInventoryVector` to conveniently call
 `startVector` with the right element size. You pass the number of
 elements you want to write. Note how you write the elements backwards since
-the buffer is being constructed back to front.
+the buffer is being constructed back to front. You then pass `inv` to the
+corresponding `Add` call when you construct the table containing it afterwards.
 
 There are `add` functions for all the scalar types. You use `addOffset` for
 any previously constructed objects (such as other tables, strings, vectors).

docs/source/Schemas.md

@@ -145,7 +145,7 @@ packages.
 
 You can include other schemas files in your current one, e.g.:
 
-    include "mydefinitions.fbs"
+    include "mydefinitions.fbs";
 
 This makes it easier to refer to types defined elsewhere. `include`
 automatically ensures each file is parsed just once, even when referred to
@@ -211,8 +211,8 @@ in the corresponding C++ code. Multiple such lines per item are allowed.
 Attributes may be attached to a declaration, behind a field, or after
 the name of a table/struct/enum/union. These may either have a value or
 not. Some attributes like `deprecated` are understood by the compiler,
-others are simply ignored (like `priority`), but are available to query
-if you parse the schema at runtime.
+others are simply ignored (like `priority` in the example above), but are
+available to query if you parse the schema at runtime.
 This is useful if you write your own code generators/editors etc., and
 you wish to add additional information specific to your tool (such as a
 help text).
@@ -254,6 +254,10 @@ Current understood attributes:
     meaning that any value N specified in the schema will end up
     representing 1<<N, or if you don't specify values at all, you'll get
     the sequence 1, 2, 4, 8, ...
+-   `nested_flatbuffer: table_name` (on a field): this indicates that the field
+    (which must be a vector of ubyte) contains flatbuffer data, for which the
+    root type is given by `table_name`. The generated code will then produce
+    a convenient accessor for the nested FlatBuffer.
 
 ## JSON Parsing