Documentation clarifications.

Change-Id: I7dc4bb3bbe32c6fe83a013790391fba0df8f4888

docs/source/CppUsage.md

@@ -42,6 +42,11 @@ correct type below. To create a vector of struct objects (which will
 be stored as contiguous memory in the buffer, use `CreateVectorOfStructs`
 instead.
 
+To create a vector of nested objects (e.g. tables, strings or other vectors)
+collect their offsets in a temporary array/vector, then call `CreateVector`
+on that (see e.g. the array of strings example in `test.cpp`
+`CreateFlatBufferTest`).
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}
     Vec3 vec(1, 2, 3);
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/source/GoUsage.md

@@ -98,7 +98,8 @@ 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. You then pass `inv` to the corresponding
+is being constructed back to front. Use the correct `Prepend` call for the type,
+or `PrependUOffsetT` for offsets. 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

docs/source/Internals.md

@@ -73,8 +73,10 @@ code.
 
 ### Tables
 
-These start with an `soffset_t` to a vtable (signed version of
-`uoffset_t`, since vtables may be stored anywhere), followed by all the
+These start with an `soffset_t` to a vtable. This is a signed version of
+`uoffset_t`, since vtables may be stored anywhere relative to the object.
+This offset is substracted (not added) from the object start to arrive at
+the vtable start. This offset is followed by all the
 fields as aligned scalars (or offsets). Unlike structs, not all fields
 need to be present. There is no set order and layout.
 
@@ -83,9 +85,9 @@ through a vtable of offsets. Vtables are shared between any objects that
 happen to have the same vtable values.
 
 The elements of a vtable are all of type `voffset_t`, which is
-a `uint16_t`. The first element is the number of elements of the vtable,
-including this one. The second one is the size of the object, in bytes
-(including the vtable offset). This size is used for streaming, to know
+a `uint16_t`. The first element is the size of the vtable in bytes,
+including the size element. The second one is the size of the object, in bytes
+(including the vtable offset). This size could be used for streaming, to know
 how many bytes to read to be able to access all fields of the object.
 The remaining elements are the N offsets, where N is the amount of fields
 declared in the schema when the code that constructed this buffer was

docs/source/Schemas.md

@@ -271,7 +271,7 @@ 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
+-   `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.