Added doc comments to the binary schema.

Change-Id: I87f291ab6e07b1425850cae25ed500db594f17c8
Tested: on Linux.

docs/source/Compiler.md

@@ -114,6 +114,8 @@ Additional options:
     to the reflection/reflection.fbs schema. Loading this binary file is the
     basis for reflection functionality.
 
+-   `--bfbs-comments`: Add doc comments to the binary schema files.
+
 -   `--conform FILE` : Specify a schema the following schemas should be
     an evolution of. Gives errors if not. Useful to check if schema
     modifications don't break schema evolution rules.

include/flatbuffers/idl.h

@@ -356,6 +356,7 @@ struct IDLOptions {
   bool union_value_namespacing;
   bool allow_non_utf8;
   std::string include_prefix;
+  bool binary_schema_comments;
 
   // Possible options for the more general generator below.
   enum Language {
@@ -396,6 +397,7 @@ struct IDLOptions {
       cpp_object_api_pointer_type("std::unique_ptr"),
       union_value_namespacing(true),
       allow_non_utf8(false),
+      binary_schema_comments(false),
       lang(IDLOptions::kJava),
       lang_to_generate(0) {}
 };

reflection/reflection.fbs

@@ -51,6 +51,7 @@ table Enum {
     is_union:bool = false;
     underlying_type:Type (required);
     attributes:[KeyValue];
+    documentation:[string];
 }
 
 table Field {
@@ -64,6 +65,7 @@ table Field {
     required:bool = false;
     key:bool = false;
     attributes:[KeyValue];
+    documentation:[string];
 }
 
 table Object {  // Used for both tables and structs.
@@ -73,6 +75,7 @@ table Object {  // Used for both tables and structs.
     minalign:int;
     bytesize:int;  // For structs.
     attributes:[KeyValue];
+    documentation:[string];
 }
 
 table Schema {

src/flatc.cpp

@@ -93,6 +93,7 @@ std::string FlatCompiler::GetUsageString(const char* program_name) const {
       "  --proto            Input is a .proto, translate to .fbs.\n"
       "  --grpc             Generate GRPC interfaces for the specified languages\n"
       "  --schema           Serialize schemas instead of JSON (use with -b)\n"
+      "  --bfbs-comments    Add doc comments to the binary schema files.\n"
       "  --conform FILE     Specify a schema the following schemas should be\n"
       "                     an evolution of. Gives errors if not.\n"
       "  --conform-includes Include path for the schema given with --conform\n"
@@ -204,6 +205,8 @@ int FlatCompiler::Compile(int argc, const char** argv) {
         exit(0);
       } else if(arg == "--grpc") {
         grpc_enabled = true;
+      } else if(arg == "--bfbs-comments") {
+        opts.binary_schema_comments = true;
       } else {
         for (size_t i = 0; i < params_.num_generators; ++i) {
           if (arg == params_.generators[i].generator_opt_long ||

src/idl_parser.cpp

@@ -2086,7 +2086,11 @@ Offset<reflection::Object> StructDef::Serialize(FlatBufferBuilder *builder,
                                   fixed,
                                   static_cast<int>(minalign),
                                   static_cast<int>(bytesize),
-                                  SerializeAttributes(builder, parser));
+                                  SerializeAttributes(builder, parser),
+                                  parser.opts.binary_schema_comments
+                                    ? builder->CreateVectorOfStrings(
+                                        doc_comment)
+                                    : 0);
 }
 
 Offset<reflection::Field> FieldDef::Serialize(FlatBufferBuilder *builder,
@@ -2106,7 +2110,10 @@ Offset<reflection::Field> FieldDef::Serialize(FlatBufferBuilder *builder,
                                  deprecated,
                                  required,
                                  key,
-                                 SerializeAttributes(builder, parser));
+                                 SerializeAttributes(builder, parser),
+                                 parser.opts.binary_schema_comments
+                                   ? builder->CreateVectorOfStrings(doc_comment)
+                                   : 0);
   // TODO: value.constant is almost always "0", we could save quite a bit of
   // space by sharing it. Same for common values of value.type.
 }
@@ -2123,7 +2130,10 @@ Offset<reflection::Enum> EnumDef::Serialize(FlatBufferBuilder *builder,
                                 builder->CreateVector(enumval_offsets),
                                 is_union,
                                 underlying_type.Serialize(builder),
-                                SerializeAttributes(builder, parser));
+                                SerializeAttributes(builder, parser),
+                                parser.opts.binary_schema_comments
+                                  ? builder->CreateVectorOfStrings(doc_comment)
+                                  : 0);
 }
 
 Offset<reflection::EnumVal> EnumVal::Serialize(FlatBufferBuilder *builder) const

tests/generate_code.sh

@@ -17,6 +17,7 @@
 ../flatc --cpp --java --csharp --go --binary --python --js --php --grpc --gen-mutable --gen-object-api --no-includes monster_test.fbs monsterdata_test.json
 ../flatc --cpp --java --csharp --go --binary --python --js --php --gen-mutable -o namespace_test namespace_test/namespace_test1.fbs namespace_test/namespace_test2.fbs
 ../flatc --cpp -o union_vector ./union_vector/union_vector.fbs
+../flatc -b --schema --bfbs-comments monster_test.fbs
 cd ../samples
 ../flatc --cpp --gen-mutable --gen-object-api monster.fbs
 cd ../reflection