Doc clarifications (Java vectors, test working dir, benchmark fix).

Change-Id: If8cc05669d82df892e1d4e11f7fbbd68b2dc05bf

docs/html/md__benchmarks.html

@@ -60,9 +60,9 @@ $(document).ready(function(){initNavTree('md__benchmarks.html','');});
 <tr>
 <th></th><th>FlatBuffers (binary) </th><th>Protocol Buffers LITE </th><th>Rapid JSON </th><th>FlatBuffers (JSON)  </th></tr>
 <tr>
-<td>Decode + Traverse + Dealloc (1 million times, seconds) </td><td>0.08 </td><td>305 </td><td>583 </td><td>105 </td></tr>
+<td>Decode + Traverse + Dealloc (1 million times, seconds) </td><td>0.08 </td><td>302 </td><td>583 </td><td>105 </td></tr>
 <tr>
-<td>Decode / Traverse / Dealloc (breakdown) </td><td>0 / 0.08 / 0 </td><td>220 / 3.6 / 81 </td><td>294 / 0.9 / 287 </td><td>70 / 0.08 / 35 </td></tr>
+<td>Decode / Traverse / Dealloc (breakdown) </td><td>0 / 0.08 / 0 </td><td>220 / 0.15 / 81 </td><td>294 / 0.9 / 287 </td><td>70 / 0.08 / 35 </td></tr>
 <tr>
 <td>Encode (1 million times, seconds) </td><td>3.2 </td><td>185 </td><td>650 </td><td>169 </td></tr>
 <tr>

docs/html/md__building.html

@@ -58,7 +58,8 @@ $(document).ready(function(){initNavTree('md__building.html','');});
 cmake -G "Visual Studio 10"
 cmake -G "Xcode"
 </pre><p>Then, build as normal for your platform. This should result in a <code>flatc</code> executable, essential for the next steps. Note that to use clang instead of gcc, you may need to set up your environment variables, e.g. <code>CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix Makefiles"</code>.</p>
-<p>Optionally, run the <code>flattests</code> executable. to ensure everything is working correctly on your system. If this fails, please contact us!</p>
+<p>Optionally, run the <code>flattests</code> executable to ensure everything is working correctly on your system. If this fails, please contact us!</p>
+<p>Note that you MUST be in the root of the FlatBuffers distribution when you run 'flattests' (and the samples), or it will fail to load its files.</p>
 <p>Building should also produce two sample executables, <code>sample_binary</code> and <code>sample_text</code>, see the corresponding <code>.cpp</code> file in the samples directory.</p>
 <p>There is an <code>android</code> directory that contains all you need to build the test executable on android (use the included <code>build_apk.sh</code> script, or use <code>ndk_build</code> / <code>adb</code> etc. as usual). Upon running, it will output to the log if tests succeeded or not.</p>
 <p>There is usually no runtime to compile, as the code consists of a single header, <code>include/flatbuffers/flatbuffers.h</code>. You should add the <code>include</code> folder to your include paths. If you wish to be able to load schemas and/or parse text into binary buffers at runtime, you additionally need the other headers in <code>include/flatbuffers</code>. You must also compile/link <code>src/idl_parser.cpp</code> (and <code>src/idl_gen_text.cpp</code> if you also want to be able convert binary to text).</p>

docs/html/md__java_usage.html

@@ -59,6 +59,7 @@ Monster monster = Monster.getRootAsMonster(bb);
 </pre><p>Now you can access values much like C++: </p><pre class="fragment">short hp = monster.hp();
 Vec3 pos = monster.pos();
 </pre><p>Note that whenever you access a new object like in the <code>pos</code> example above, a new temporary accessor object gets created. If your code is very performance sensitive (you iterate through a lot of objects), there's a second <code>pos()</code> method to which you can pass a <code>Vec3</code> object you've already created. This allows you to reuse it across many calls and reduce the amount of object allocation (and thus garbage collection) your program does.</p>
+<p>Java does not support unsigned scalars. This means that any unsigned types you use in your schema will actually be represented as a signed value. This means all bits are still present, but may represent a negative value when used. For example, to read a <code>byte b</code> as an unsigned number, you can do: <code>(short)(b &amp; 0xFF)</code></p>
 <p>Sadly the string accessors currently always create a new string when accessed, since FlatBuffer's UTF-8 strings can't be read in-place by Java.</p>
 <p>Vector access is also a bit different from C++: you pass an extra index to the vector field accessor. Then a second method with the same name suffixed by <code>_length</code> let's you know the number of elements you can access: </p><pre class="fragment">for (int i = 0; i &lt; monster.inventory_length(); i++)
     monster.inventory(i); // do something here
@@ -78,6 +79,7 @@ int mon = Monster.endMonster(fbb);
 for (byte i = 4; i &gt;=0; i--) fbb.addByte(i);
 int inv = fbb.endVector();
 </pre><p>You can use the generated method <code>startInventoryVector</code> to conveniently call <code>startVector</code> with the right element size. You pass the number of elements you want to write. You write the elements backwards since the buffer is being constructed back to front.</p>
+<p>There are <code>add</code> functions for all the scalar types. You use <code>addOffset</code> for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate <code>create</code> function in-line, as shown above in the <code>Monster</code> example.</p>
 <h2>Text Parsing</h2>
 <p>There currently is no support for parsing text (Schema's and JSON) directly from Java, though you could use the C++ parser through JNI. Please see the C++ documentation for more on text parsing. </p>
 </div></div><!-- contents -->

docs/source/Benchmarks.md

@@ -15,8 +15,8 @@ meant to be representative of game data, e.g. a scene format.
 
 |                                                        | FlatBuffers (binary)  | Protocol Buffers LITE | Rapid JSON            | FlatBuffers (JSON)    |
 |--------------------------------------------------------|-----------------------|-----------------------|-----------------------|-----------------------|
-| Decode + Traverse + Dealloc (1 million times, seconds) | 0.08                  | 305                   | 583                   | 105                   |
+| Decode + Traverse + Dealloc (1 million times, seconds) | 0.08                  | 302                   | 583                   | 105                   |
-| Decode / Traverse / Dealloc (breakdown)                | 0 / 0.08 / 0          | 220 / 3.6 / 81        | 294 / 0.9 / 287       | 70 / 0.08 / 35        |
+| Decode / Traverse / Dealloc (breakdown)                | 0 / 0.08 / 0          | 220 / 0.15 / 81       | 294 / 0.9 / 287       | 70 / 0.08 / 35        |
 | Encode (1 million times, seconds)                      | 3.2                   | 185                   | 650                   | 169                   |
 | Wire format size (normal / zlib, bytes)                | 344 / 220             | 228 / 174             | 1475 / 322            | 1029 / 298            |
 | Memory needed to store decoded wire (bytes / blocks)   | 0 / 0                 | 760 / 20              | 65689 / 40            | 328 / 1               |

docs/source/Building.md

@@ -18,9 +18,11 @@ Note that to use clang instead of gcc, you may need to set up your environment
 variables, e.g.
 `CC=/usr/bin/clang CXX=/usr/bin/clang++ cmake -G "Unix Makefiles"`.
 
-Optionally, run the `flattests` executable.
+Optionally, run the `flattests` executable to ensure everything is working
-to ensure everything is working correctly on your system. If this fails,
+correctly on your system. If this fails, please contact us!
-please contact us!
+
+Note that you MUST be in the root of the FlatBuffers distribution when you
+run 'flattests' (and the samples), or it will fail to load its files.
 
 Building should also produce two sample executables, `sample_binary` and
 `sample_text`, see the corresponding `.cpp` file in the samples directory.

docs/source/JavaUsage.md

@@ -22,6 +22,12 @@ method to which you can pass a `Vec3` object you've already created. This allows
 you to reuse it across many calls and reduce the amount of object allocation (and
 thus garbage collection) your program does.
 
+Java does not support unsigned scalars. This means that any unsigned types you
+use in your schema will actually be represented as a signed value. This means
+all bits are still present, but may represent a negative value when used.
+For example, to read a `byte b` as an unsigned number, you can do:
+`(short)(b & 0xFF)`
+
 Sadly the string accessors currently always create a new string when accessed,
 since FlatBuffer's UTF-8 strings can't be read in-place by Java.
 
@@ -72,6 +78,11 @@ You can use the generated method `startInventoryVector` to conveniently call
 elements you want to write. You write the elements backwards since the buffer
 is being constructed back to front.
 
+There are `add` functions for all the scalar types. You use `addOffset` 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.
+
 ## Text Parsing
 
 There currently is no support for parsing text (Schema's and JSON) directly