Various documentation clarifications.

Change-Id: Ibc2bd88a636f3b4abf82a7c2722fc1e354dab848
Tested: on Linux.

10 files changed, 52 insertions, 25 deletions

diff --git a/docs/html/index.html b/docs/html/index.html
index ab9ec47b..639c1dae 100644
--- a/docs/html/index.html
+++ b/docs/html/index.html
@@ -53,7 +53,7 @@ $(document).ready(function(){initNavTree('index.html','');});
 <div class="title">FlatBuffers Documentation</div>  </div>
 </div><!--header-->
 <div class="contents">
-<div class="textblock"><p>FlatBuffers is an efficient cross platform serialization library for C++, with support for Java and Go. It was created at Google specifically for game development and other performance-critical applications.</p>
+<div class="textblock"><p>FlatBuffers is an efficient cross platform serialization library for C++, with support for Java, C# and Go. It was created at Google specifically for game development and other performance-critical applications.</p>
 <p>It is available as open source under the Apache license, v2 (see LICENSE.txt).</p>
 <h2>Why use FlatBuffers?</h2>
 <ul>
@@ -65,7 +65,7 @@ $(document).ready(function(){initNavTree('index.html','');});
 <li><p class="startli"><b>Convenient to use</b> - Generated C++ code allows for terse access &amp; construction code. Then there's optional functionality for parsing schemas and JSON-like text representations at runtime efficiently if needed (faster and more memory efficient than other JSON parsers).</p>
 <p class="startli">Java and Go code supports object-reuse.</p>
 </li>
-<li><b>Cross platform C++11/Java/Go code with no dependencies</b> - will work with any recent gcc/clang and VS2010. Comes with build files for the tests &amp; samples (Android .mk files, and cmake for all other platforms).</li>
+<li><b>Cross platform C++11/Java/C#/Go code with no dependencies</b> - will work with any recent gcc/clang and VS2010. Comes with build files for the tests &amp; samples (Android .mk files, and cmake for all other platforms).</li>
 </ul>
 <h3>Why not use Protocol Buffers, or .. ?</h3>
 <p>Protocol Buffers is indeed relatively similar to FlatBuffers, with the primary difference being that FlatBuffers does not need a parsing/ unpacking step to a secondary representation before you can access data, often coupled with per-object memory allocation. The code is an order of magnitude bigger, too. Protocol Buffers has neither optional text import/export nor schema language features like unions.</p>
@@ -76,7 +76,7 @@ $(document).ready(function(){initNavTree('index.html','');});
 <p>This section is a quick rundown of how to use this system. Subsequent sections provide a more in-depth usage guide.</p>
 <ul>
 <li>Write a schema file that allows you to define the data structures you may want to serialize. Fields can have a scalar type (ints/floats of all sizes), or they can be a: string; array of any type; reference to yet another object; or, a set of possible objects (unions). Fields are optional and have defaults, so they don't need to be present for every object instance.</li>
-<li>Use <code>flatc</code> (the FlatBuffer compiler) to generate a C++ header (or Java/Go classes) with helper classes to access and construct serialized data. This header (say <code>mydata_generated.h</code>) only depends on <code>flatbuffers.h</code>, which defines the core functionality.</li>
+<li>Use <code>flatc</code> (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 <code>mydata_generated.h</code>) only depends on <code>flatbuffers.h</code>, which defines the core functionality.</li>
 <li>Use the <code>FlatBufferBuilder</code> class to construct a flat binary buffer. The generated functions allow you to add objects to this buffer recursively, often as simply as making a single function call.</li>
 <li>Store or send your buffer somewhere!</li>
 <li>When reading it back, you can obtain the pointer to the root object from the binary buffer, and from there traverse it conveniently in-place with <code>object-&gt;field()</code>.</li>
@@ -87,7 +87,7 @@ $(document).ready(function(){initNavTree('index.html','');});
 <li>How to <a href="md__compiler.html">use the compiler</a>.</li>
 <li>How to <a href="md__schemas.html">write a schema</a>.</li>
 <li>How to <a href="md__cpp_usage.html">use the generated C++ code</a> in your own programs.</li>
-<li>How to <a href="md__java_usage.html">use the generated Java code</a> in your own programs.</li>
+<li>How to <a href="md__java_usage.html">use the generated Java/C# code</a> in your own programs.</li>
 <li>How to <a href="md__go_usage.html">use the generated Go code</a> in your own programs.</li>
 <li>Some <a href="md__benchmarks.html">benchmarks</a> showing the advantage of using FlatBuffers.</li>
 <li>A <a href="md__white_paper.html">white paper</a> explaining the "why" of FlatBuffers.</li>
diff --git a/docs/html/md__cpp_usage.html b/docs/html/md__cpp_usage.html
index d71a278b..0a7ac1f5 100644
--- a/docs/html/md__cpp_usage.html
+++ b/docs/html/md__cpp_usage.html
@@ -86,7 +86,7 @@ $(document).ready(function(){initNavTree('md__cpp_usage.html','');});
 <h3>Reading in C++</h3>
 <p>If you've received a buffer from somewhere (disk, network, etc.) you can directly start traversing it using:</p>
 <div class="fragment"><div class="line"><span class="keyword">auto</span> monster = GetMonster(buffer_pointer);</div>
-</div><!-- fragment --><p><code>monster</code> is of type <code>Monster *</code>, and points to somewhere inside your buffer. If you look in your generated header, you'll see it has convenient accessors for all fields, e.g.</p>
+</div><!-- fragment --><p><code>monster</code> is of type <code>Monster *</code>, and points to somewhere <em>inside</em> your buffer (root object pointers are not the same as <code>buffer_pointer</code> !). If you look in your generated header, you'll see it has convenient accessors for all fields, e.g.</p>
 <div class="fragment"><div class="line">assert(monster-&gt;hp() == 80);</div>
 <div class="line">assert(monster-&gt;mana() == 150);  <span class="comment">// default</span></div>
 <div class="line">assert(strcmp(monster-&gt;name()-&gt;c_str(), <span class="stringliteral">&quot;MyMonster&quot;</span>) == 0);</div>
diff --git a/docs/html/md__java_usage.html b/docs/html/md__java_usage.html
index 9e3f2a62..25d325ef 100644
--- a/docs/html/md__java_usage.html
+++ b/docs/html/md__java_usage.html
@@ -4,7 +4,7 @@
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
 <meta name="generator" content="Doxygen 1.8.7"/>
-<title>FlatBuffers: Use in Java</title>
+<title>FlatBuffers: Use in Java/C</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="dynsections.js"></script>
@@ -50,10 +50,11 @@ $(document).ready(function(){initNavTree('md__java_usage.html','');});
 <div id="doc-content">
 <div class="header">
   <div class="headertitle">
-<div class="title">Use in Java </div>  </div>
+<div class="title">Use in Java/C </div>  </div>
 </div><!--header-->
 <div class="contents">
-<div class="textblock"><p>FlatBuffers supports reading and writing binary FlatBuffers in Java. Generate code for Java with the <code>-j</code> option to <code>flatc</code>.</p>
+<div class="textblock"><p>FlatBuffers supports reading and writing binary FlatBuffers in Java and C#. Generate code for Java with the <code>-j</code> option to <code>flatc</code>, or for C# with <code>-n</code> (think .Net).</p>
+<p>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 <code>camelCase</code> Java call will be <code>CamelCase</code> in C#.</p>
 <p>See <code>javaTest.java</code> for an example. Essentially, you read a FlatBuffer binary file into a <code>byte[]</code>, which you then turn into a <code>ByteBuffer</code>, which you pass to the <code>getRootAsMyRootType</code> function:</p>
 <div class="fragment"><div class="line">ByteBuffer bb = ByteBuffer.wrap(data);</div>
 <div class="line">Monster monster = Monster.getRootAsMonster(bb);</div>
diff --git a/docs/html/md__schemas.html b/docs/html/md__schemas.html
index daa5ab37..e154a202 100644
--- a/docs/html/md__schemas.html
+++ b/docs/html/md__schemas.html
@@ -93,12 +93,15 @@ root_type Monster;
 <h3>Structs</h3>
 <p>Similar to a table, only now none of the fields are optional (so no defaults either), and fields may not be added or be deprecated. Structs may only contain scalars or other structs. Use this for simple objects where you are very sure no changes will ever be made (as quite clear in the example <code>Vec3</code>). Structs use less memory than tables and are even faster to access (they are always stored in-line in their parent object, and use no virtual table).</p>
 <h3>Types</h3>
-<p>Builtin scalar types are:</p>
+<p>Built-in scalar types are:</p>
 <ul>
 <li>8 bit: <code>byte ubyte bool</code></li>
 <li>16 bit: <code>short ushort</code></li>
 <li>32 bit: <code>int uint float</code></li>
 <li>64 bit: <code>long ulong double</code></li>
+</ul>
+<p>Built-in non-scalar types:</p>
+<ul>
 <li>Vector of any other type (denoted with <code>[type]</code>). Nesting vectors is not supported, instead you can wrap the inner vector in a table.</li>
 <li><code>string</code>, which may only hold UTF-8 or 7-bit ASCII. For other text encodings or general binary data use vectors (<code>[byte]</code> or <code>[ubyte]</code>) instead.</li>
 <li>References to other tables or structs, enums or unions (see below).</li>
@@ -111,6 +114,8 @@ root_type Monster;
 <p>Define a sequence of named constants, each with a given value, or increasing by one from the previous one. The default first value is <code>0</code>. As you can see in the enum declaration, you specify the underlying integral type of the enum with <code>:</code> (in this case <code>byte</code>), which then determines the type of any fields declared with this enum type.</p>
 <h3>Unions</h3>
 <p>Unions share a lot of properties with enums, but instead of new names for constants, you use names of tables. You can then declare a union field which can hold a reference to any of those types, and additionally a hidden field with the suffix <code>_type</code> is generated that holds the corresponding enum value, allowing you to know which type to cast to at runtime.</p>
+<p>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.</p>
+<p>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.</p>
 <h3>Namespaces</h3>
 <p>These will generate the corresponding namespace in C++ for all helper code, and packages in Java. You can use <code>.</code> to specify nested namespaces / packages.</p>
 <h3>Includes</h3>
@@ -126,6 +131,7 @@ root_type Monster;
 </pre><p>Identifiers must always be exactly 4 characters long. These 4 characters will end up as bytes at offsets 4-7 (inclusive) in the buffer.</p>
 <p>For any schema that has such an identifier, <code>flatc</code> will automatically add the identifier to any binaries it generates (with <code>-b</code>), and generated calls like <code>FinishMonsterBuffer</code> also add the identifier. If you have specified an identifier and wish to generate a buffer without one, you can always still do so by calling <code>FlatBufferBuilder::Finish</code> explicitly.</p>
 <p>After loading a buffer, you can use a call like <code>MonsterBufferHasIdentifier</code> to check if the identifier is present.</p>
+<p>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.</p>
 <p>Additionally, by default <code>flatc</code> will output binary files as <code>.bin</code>. This declaration in the schema will change that to whatever you want: </p><pre class="fragment">file_extension "ext";
 </pre><h3>Comments &amp; documentation</h3>
 <p>May be written as in most C-based languages. Additionally, a triple comment (<code>///</code>) on a line by itself signals that a comment is documentation for whatever is declared on the line after it (table/struct/field/enum/union/element), and the comment is output in the corresponding C++ code. Multiple such lines per item are allowed.</p>
diff --git a/docs/html/navtree.js b/docs/html/navtree.js
index 9ff8c25e..70056c0b 100644
--- a/docs/html/navtree.js
+++ b/docs/html/navtree.js
@@ -6,7 +6,7 @@ var NAVTREE =
     [ "Writing a schema", "md__schemas.html", null ],
     [ "Use in C++", "md__cpp_usage.html", null ],
     [ "Use in Go", "md__go_usage.html", null ],
-    [ "Use in Java", "md__java_usage.html", null ],
+    [ "Use in Java/C", "md__java_usage.html", null ],
     [ "Benchmarks", "md__benchmarks.html", null ],
     [ "FlatBuffers white paper", "md__white_paper.html", null ],
     [ "FlatBuffer Internals", "md__internals.html", null ],
diff --git a/docs/html/pages.html b/docs/html/pages.html
index 5810c722..30291b36 100644
--- a/docs/html/pages.html
+++ b/docs/html/pages.html
@@ -60,7 +60,7 @@ $(document).ready(function(){initNavTree('pages.html','');});
 <tr id="row_2_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__schemas.html" target="_self">Writing a schema</a></td><td class="desc"></td></tr>
 <tr id="row_3_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__cpp_usage.html" target="_self">Use in C++</a></td><td class="desc"></td></tr>
 <tr id="row_4_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__go_usage.html" target="_self">Use in Go</a></td><td class="desc"></td></tr>
-<tr id="row_5_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__java_usage.html" target="_self">Use in Java</a></td><td class="desc"></td></tr>
+<tr id="row_5_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__java_usage.html" target="_self">Use in Java/C</a></td><td class="desc"></td></tr>
 <tr id="row_6_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__benchmarks.html" target="_self">Benchmarks</a></td><td class="desc"></td></tr>
 <tr id="row_7_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__white_paper.html" target="_self">FlatBuffers white paper</a></td><td class="desc"></td></tr>
 <tr id="row_8_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__internals.html" target="_self">FlatBuffer Internals</a></td><td class="desc"></td></tr>
diff --git a/docs/source/CppUsage.md b/docs/source/CppUsage.md
index a941ce40..62c45d81 100755
--- a/docs/source/CppUsage.md
+++ b/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}
diff --git a/docs/source/FlatBuffers.md b/docs/source/FlatBuffers.md
index fd308555..05e8c8e6 100644
--- a/docs/source/FlatBuffers.md
+++ b/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.
diff --git a/docs/source/JavaUsage.md b/docs/source/JavaUsage.md
index e6321b65..9586f4c5 100755
--- a/docs/source/JavaUsage.md
+++ b/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
diff --git a/docs/source/Schemas.md b/docs/source/Schemas.md
index 9d568d02..9fce3366 100755
--- a/docs/source/Schemas.md
+++ b/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: