Various documentation clarifications.

Change-Id: Ibc2bd88a636f3b4abf82a7c2722fc1e354dab848
Tested: on Linux.

docs/source/CppUsage.md

@@ -119,8 +119,9 @@ directly start traversing it using:
     auto monster = GetMonster(buffer_pointer);
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-`monster` is of type `Monster *`, and points to somewhere inside your
-buffer. If you look in your generated header, you'll see it has
+`monster` is of type `Monster *`, and points to somewhere *inside* your
+buffer (root object pointers are not the same as `buffer_pointer` !).
+If you look in your generated header, you'll see it has
 convenient accessors for all fields, e.g.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cpp}

docs/source/FlatBuffers.md

@@ -1,7 +1,7 @@
 # FlatBuffers
 
 FlatBuffers is an efficient cross platform serialization library for C++,
-with support for Java and Go. It was created at Google specifically for game
+with support for Java, C# and Go. It was created at Google specifically for game
 development and other performance-critical applications.
 
 It is available as open source under the Apache license, v2 (see LICENSE.txt).
@@ -48,8 +48,8 @@ It is available as open source under the Apache license, v2 (see LICENSE.txt).
 
     Java and Go code supports object-reuse.
 
--   **Cross platform C++11/Java/Go code with no dependencies** - will work with
-    any recent gcc/clang and VS2010. Comes with build files for the tests &
+-   **Cross platform C++11/Java/C#/Go code with no dependencies** - will work
+    with any recent gcc/clang and VS2010. Comes with build files for the tests &
     samples (Android .mk files, and cmake for all other platforms).
 
 ### Why not use Protocol Buffers, or .. ?
@@ -87,10 +87,10 @@ sections provide a more in-depth usage guide.
     Fields are optional and have defaults, so they don't need to be
     present for every object instance.
 
--   Use `flatc` (the FlatBuffer compiler) to generate a C++ header (or Java/Go
-    classes) with helper classes to access and construct serialized data. This
-    header (say `mydata_generated.h`) only depends on `flatbuffers.h`, which
-    defines the core functionality.
+-   Use `flatc` (the FlatBuffer compiler) to generate a C++ header (or
+    Java/C#/Go classes) with helper classes to access and construct serialized
+    data. This header (say `mydata_generated.h`) only depends on
+    `flatbuffers.h`, which defines the core functionality.
 
 -   Use the `FlatBufferBuilder` class to construct a flat binary buffer.
     The generated functions allow you to add objects to this
@@ -110,7 +110,7 @@ sections provide a more in-depth usage guide.
 -   How to [write a schema](md__schemas.html).
 -   How to [use the generated C++ code](md__cpp_usage.html) in your own
     programs.
--   How to [use the generated Java code](md__java_usage.html) in your own
+-   How to [use the generated Java/C# code](md__java_usage.html) in your own
     programs.
 -   How to [use the generated Go code](md__go_usage.html) in your own
     programs.

docs/source/JavaUsage.md

@@ -1,7 +1,12 @@
-# Use in Java
+# Use in Java/C#
 
-FlatBuffers supports reading and writing binary FlatBuffers in Java. Generate
-code for Java with the `-j` option to `flatc`.
+FlatBuffers supports reading and writing binary FlatBuffers in Java and C#.
+Generate code for Java with the `-j` option to `flatc`, or for C# with `-n`
+(think .Net).
+
+Note that this document is from the perspective of Java. Code for both languages
+is generated in the same way, with only very subtle differences, for example
+any `camelCase` Java call will be `CamelCase` in C#.
 
 See `javaTest.java` for an example. Essentially, you read a FlatBuffer binary
 file into a `byte[]`, which you then turn into a `ByteBuffer`, which you pass to

docs/source/Schemas.md

@@ -82,7 +82,7 @@ parent object, and use no virtual table).
 
 ### Types
 
-Builtin scalar types are:
+Built-in scalar types are:
 
 -   8 bit: `byte ubyte bool`
 
@@ -92,6 +92,8 @@ Builtin scalar types are:
 
 -   64 bit: `long ulong double`
 
+Built-in non-scalar types:
+
 -   Vector of any other type (denoted with `[type]`). Nesting vectors
     is not supported, instead you can wrap the inner vector in a table.
 
@@ -137,6 +139,14 @@ additionally a hidden field with the suffix `_type` is generated that
 holds the corresponding enum value, allowing you to know which type to
 cast to at runtime.
 
+Unions are a good way to be able to send multiple message types as a FlatBuffer.
+Note that because a union field is really two fields, it must always be
+part of a table, it cannot be the root of a FlatBuffer by itself.
+
+If you have a need to distinguish between different FlatBuffers in a more
+open-ended way, for example for use as files, see the file identification
+feature below.
+
 ### Namespaces
 
 These will generate the corresponding namespace in C++ for all helper
@@ -195,6 +205,10 @@ without one, you can always still do so by calling
 After loading a buffer, you can use a call like
 `MonsterBufferHasIdentifier` to check if the identifier is present.
 
+Note that this is best for open-ended uses such as files. If you simply wanted
+to send one of a set of possible messages over a network for example, you'd
+be better off with a union.
+
 Additionally, by default `flatc` will output binary files as `.bin`.
 This declaration in the schema will change that to whatever you want: