Revamping the FlatBuffers docs.

Adding an API reference for the supported languages.

General docs cleanup, including a new `tutorial` section that
supports all of the supported languages.

Added samples for each supported language to mirror the new
tutorial page.

Cleaned up all the links by making them `@ref` style links,
instead of referencing the names of the generated `.html` files.

Removed all generated files that were unnecessarily committed.

Also fixed the C# tests (two were failing due to a missing file).

Bug: b/25801305

Tested: Tested all samples on Ubuntu, Mac, and Android. Docs were
generated using doxygen and viewed on Chrome.

Change-Id: I2acaba6e332a15ae2deff5f26a4a25da7bd2c954

java/com/google/flatbuffers/Table.java

@@ -20,34 +20,61 @@ import static com.google.flatbuffers.Constants.*;
 import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
 
-// All tables in the generated code derive from this class, and add their own accessors.
+/// @cond FLATBUFFERS_INTERNAL
+
+/**
+ * All tables in the generated code derive from this class, and add their own accessors.
+ */
 public class Table {
+  /** Used to hold the position of the `bb` buffer. */
   protected int bb_pos;
+  /** The underlying ByteBuffer to hold the data of the Table. */
   protected ByteBuffer bb;
 
+  /**
+   * Get the underlying ByteBuffer.
+   *
+   * @return Returns the Table's ByteBuffer.
+   */
   public ByteBuffer getByteBuffer() { return bb; }
 
-  // Look up a field in the vtable, return an offset into the object, or 0 if the field is not
-  // present.
+  /**
+   * Look up a field in the vtable.
+   *
+   * @param vtable_offset An `int` offset to the vtable in the Table's ByteBuffer.
+   * @return Returns an offset into the object, or `0` if the field is not present.
+   */
   protected int __offset(int vtable_offset) {
     int vtable = bb_pos - bb.getInt(bb_pos);
     return vtable_offset < bb.getShort(vtable) ? bb.getShort(vtable + vtable_offset) : 0;
   }
 
-  // Retrieve the relative offset stored at "offset"
+  /**
+   * Retrieve a relative offset.
+   *
+   * @param offset An `int` index into the Table's ByteBuffer containing the relative offset.
+   * @return Returns the relative offset stored at `offset`.
+   */
   protected int __indirect(int offset) {
     return offset + bb.getInt(offset);
   }
 
-  // Create a java String from UTF-8 data stored inside the flatbuffer.
-  // This allocates a new string and converts to wide chars upon each access,
-  // which is not very efficient. Instead, each FlatBuffer string also comes with an
-  // accessor based on __vector_as_bytebuffer below, which is much more efficient,
-  // assuming your Java program can handle UTF-8 data directly.
+  /**
+   * Create a Java `String` from UTF-8 data stored inside the FlatBuffer.
+   *
+   * This allocates a new string and converts to wide chars upon each access,
+   * which is not very efficient. Instead, each FlatBuffer string also comes with an
+   * accessor based on __vector_as_bytebuffer below, which is much more efficient,
+   * assuming your Java program can handle UTF-8 data directly.
+   *
+   * @param offset An `int` index into the Table's ByteBuffer.
+   * @return Returns a `String` from the data stored inside the FlatBuffer at `offset`.
+   */
   protected String __string(int offset) {
     offset += bb.getInt(offset);
     if (bb.hasArray()) {
-      return new String(bb.array(), bb.arrayOffset() + offset + SIZEOF_INT, bb.getInt(offset), FlatBufferBuilder.utf8charset);
+      return new String(bb.array(), bb.arrayOffset() + offset + SIZEOF_INT, bb.getInt(offset),
+                        FlatBufferBuilder.utf8charset);
     } else {
       // We can't access .array(), since the ByteBuffer is read-only,
       // off-heap or a memory map
@@ -60,23 +87,36 @@ public class Table {
     }
   }
 
-  // Get the length of a vector whose offset is stored at "offset" in this object.
+  /**
+   * Get the length of a vector.
+   *
+   * @param offset An `int` index into the Table's ByteBuffer.
+   * @return Returns the length of the vector whose offset is stored at `offset`.
+   */
   protected int __vector_len(int offset) {
     offset += bb_pos;
     offset += bb.getInt(offset);
     return bb.getInt(offset);
   }
 
-  // Get the start of data of a vector whose offset is stored at "offset" in this object.
+  /**
+   * Get the start data of a vector.
+   *
+   * @param offset An `int` index into the Table's ByteBuffer.
+   * @return Returns the start of the vector data whose offset is stored at `offset`.
+   */
   protected int __vector(int offset) {
     offset += bb_pos;
     return offset + bb.getInt(offset) + SIZEOF_INT;  // data starts after the length
   }
 
-  // Get a whole vector as a ByteBuffer. This is efficient, since it only allocates a new
-  // bytebuffer object, but does not actually copy the data, it still refers to the same
-  // bytes as the original ByteBuffer.
-  // Also useful with nested FlatBuffers etc.
+  /**
+   * Get a whole vector as a ByteBuffer.
+   *
+   * This is efficient, since it only allocates a new bytebuffer object, but does not actually copy
+   * the data, it still refers to the same bytes as the original ByteBuffer. Also useful with nested
+   * FlatBuffers, etc.
+   */
   protected ByteBuffer __vector_as_bytebuffer(int vector_offset, int elem_size) {
     int o = __offset(vector_offset);
     if (o == 0) return null;
@@ -87,7 +127,13 @@ public class Table {
     return bb;
   }
 
-  // Initialize any Table-derived type to point to the union at the given offset.
+  /**
+   * Initialize any Table-derived type to point to the union at the given `offset`.
+   *
+   * @param t A `Table`-derived type that should point to the union at `offset`.
+   * @param offset An `int` index into the Table's ByteBuffer.
+   * @return Returns the Table that points to the union at `offset`.
+   */
   protected Table __union(Table t, int offset) {
     offset += bb_pos;
     t.bb_pos = offset + bb.getInt(offset);
@@ -95,6 +141,12 @@ public class Table {
     return t;
   }
 
+  /**
+   * Check if a ByteBuffer contains a file identifier.
+   *
+   * @param bb A `ByteBuffer` to check if it contains the identifier `ident`.
+   * @param ident A `String` identifier of the flatbuffer file.
+   */
   protected static boolean __has_identifier(ByteBuffer bb, String ident) {
     if (ident.length() != FILE_IDENTIFIER_LENGTH)
         throw new AssertionError("FlatBuffers: file identifier must be length " +
@@ -105,3 +157,5 @@ public class Table {
     return true;
   }
 }
+
+/// @endcond