Skip to content

Commit

Permalink
Added doc comments to the binary schema.
Browse files Browse the repository at this point in the history 
Change-Id: I87f291ab6e07b1425850cae25ed500db594f17c8
Tested: on Linux.
  • Loading branch information
@aardappel
aardappel committed Feb 14, 2017
1 parent 2d6e8f0 commit 1fb6b9e
Show file tree
Hide file tree
Showing 8 changed files with 81 additions and 18 deletions.
2 changes: 2 additions & 0 deletions docs/source/Compiler.md
View file
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions include/flatbuffers/idl.h
View file
Expand Up @@ -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 {
Expand Down Expand Up @@ -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) {}
};
Expand Down
72 changes: 57 additions & 15 deletions include/flatbuffers/reflection_generated.h
View file
Expand Up @@ -294,7 +294,8 @@ struct Enum FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
VT_VALUES = 6,
VT_IS_UNION = 8,
VT_UNDERLYING_TYPE = 10,
VT_ATTRIBUTES = 12
VT_ATTRIBUTES = 12,
VT_DOCUMENTATION = 14
};
const flatbuffers::String *name() const {
return GetPointer<const flatbuffers::String *>(VT_NAME);
Expand All @@ -317,6 +318,9 @@ struct Enum FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
const flatbuffers::Vector<flatbuffers::Offset<KeyValue>> *attributes() const {
return GetPointer<const flatbuffers::Vector<flatbuffers::Offset<KeyValue>> *>(VT_ATTRIBUTES);
}
const flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>> *documentation() const {
return GetPointer<const flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>> *>(VT_DOCUMENTATION);
}
bool Verify(flatbuffers::Verifier &verifier) const {
return VerifyTableStart(verifier) &&
VerifyFieldRequired<flatbuffers::uoffset_t>(verifier, VT_NAME) &&
Expand All @@ -330,6 +334,9 @@ struct Enum FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
VerifyField<flatbuffers::uoffset_t>(verifier, VT_ATTRIBUTES) &&
verifier.Verify(attributes()) &&
verifier.VerifyVectorOfTables(attributes()) &&
VerifyField<flatbuffers::uoffset_t>(verifier, VT_DOCUMENTATION) &&
verifier.Verify(documentation()) &&
verifier.VerifyVectorOfStrings(documentation()) &&
verifier.EndTable();
}
};
Expand All @@ -352,13 +359,16 @@ struct EnumBuilder {
void add_attributes(flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<KeyValue>>> attributes) {
fbb_.AddOffset(Enum::VT_ATTRIBUTES, attributes);
}
void add_documentation(flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>>> documentation) {
fbb_.AddOffset(Enum::VT_DOCUMENTATION, documentation);
}
EnumBuilder(flatbuffers::FlatBufferBuilder &_fbb)
: fbb_(_fbb) {
start_ = fbb_.StartTable();
}
EnumBuilder &operator=(const EnumBuilder &);
flatbuffers::Offset<Enum> Finish() {
const auto end = fbb_.EndTable(start_, 5);
const auto end = fbb_.EndTable(start_, 6);
auto o = flatbuffers::Offset<Enum>(end);
fbb_.Required(o, Enum::VT_NAME);
fbb_.Required(o, Enum::VT_VALUES);
Expand All @@ -373,8 +383,10 @@ inline flatbuffers::Offset<Enum> CreateEnum(
flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<EnumVal>>> values = 0,
bool is_union = false,
flatbuffers::Offset<Type> underlying_type = 0,
flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<KeyValue>>> attributes = 0) {
flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<KeyValue>>> attributes = 0,
flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>>> documentation = 0) {
EnumBuilder builder_(_fbb);
builder_.add_documentation(documentation);
builder_.add_attributes(attributes);
builder_.add_underlying_type(underlying_type);
builder_.add_values(values);
Expand All @@ -389,14 +401,16 @@ inline flatbuffers::Offset<Enum> CreateEnumDirect(
const std::vector<flatbuffers::Offset<EnumVal>> *values = nullptr,
bool is_union = false,
flatbuffers::Offset<Type> underlying_type = 0,
const std::vector<flatbuffers::Offset<KeyValue>> *attributes = nullptr) {
const std::vector<flatbuffers::Offset<KeyValue>> *attributes = nullptr,
const std::vector<flatbuffers::Offset<flatbuffers::String>> *documentation = nullptr) {
return reflection::CreateEnum(
_fbb,
name ? _fbb.CreateString(name) : 0,
values ? _fbb.CreateVector<flatbuffers::Offset<EnumVal>>(*values) : 0,
is_union,
underlying_type,
attributes ? _fbb.CreateVector<flatbuffers::Offset<KeyValue>>(*attributes) : 0);
attributes ? _fbb.CreateVector<flatbuffers::Offset<KeyValue>>(*attributes) : 0,
documentation ? _fbb.CreateVector<flatbuffers::Offset<flatbuffers::String>>(*documentation) : 0);
}

struct Field FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
Expand All @@ -410,7 +424,8 @@ struct Field FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
VT_DEPRECATED = 16,
VT_REQUIRED = 18,
VT_KEY = 20,
VT_ATTRIBUTES = 22
VT_ATTRIBUTES = 22,
VT_DOCUMENTATION = 24
};
const flatbuffers::String *name() const {
return GetPointer<const flatbuffers::String *>(VT_NAME);
Expand Down Expand Up @@ -448,6 +463,9 @@ struct Field FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
const flatbuffers::Vector<flatbuffers::Offset<KeyValue>> *attributes() const {
return GetPointer<const flatbuffers::Vector<flatbuffers::Offset<KeyValue>> *>(VT_ATTRIBUTES);
}
const flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>> *documentation() const {
return GetPointer<const flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>> *>(VT_DOCUMENTATION);
}
bool Verify(flatbuffers::Verifier &verifier) const {
return VerifyTableStart(verifier) &&
VerifyFieldRequired<flatbuffers::uoffset_t>(verifier, VT_NAME) &&
Expand All @@ -464,6 +482,9 @@ struct Field FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
VerifyField<flatbuffers::uoffset_t>(verifier, VT_ATTRIBUTES) &&
verifier.Verify(attributes()) &&
verifier.VerifyVectorOfTables(attributes()) &&
VerifyField<flatbuffers::uoffset_t>(verifier, VT_DOCUMENTATION) &&
verifier.Verify(documentation()) &&
verifier.VerifyVectorOfStrings(documentation()) &&
verifier.EndTable();
}
};
Expand Down Expand Up @@ -501,13 +522,16 @@ struct FieldBuilder {
void add_attributes(flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<KeyValue>>> attributes) {
fbb_.AddOffset(Field::VT_ATTRIBUTES, attributes);
}
void add_documentation(flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>>> documentation) {
fbb_.AddOffset(Field::VT_DOCUMENTATION, documentation);
}
FieldBuilder(flatbuffers::FlatBufferBuilder &_fbb)
: fbb_(_fbb) {
start_ = fbb_.StartTable();
}
FieldBuilder &operator=(const FieldBuilder &);
flatbuffers::Offset<Field> Finish() {
const auto end = fbb_.EndTable(start_, 10);
const auto end = fbb_.EndTable(start_, 11);
auto o = flatbuffers::Offset<Field>(end);
fbb_.Required(o, Field::VT_NAME);
fbb_.Required(o, Field::VT_TYPE);
Expand All @@ -526,10 +550,12 @@ inline flatbuffers::Offset<Field> CreateField(
bool deprecated = false,
bool required = false,
bool key = false,
flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<KeyValue>>> attributes = 0) {
flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<KeyValue>>> attributes = 0,
flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>>> documentation = 0) {
FieldBuilder builder_(_fbb);
builder_.add_default_real(default_real);
builder_.add_default_integer(default_integer);
builder_.add_documentation(documentation);
builder_.add_attributes(attributes);
builder_.add_type(type);
builder_.add_name(name);
Expand All @@ -552,7 +578,8 @@ inline flatbuffers::Offset<Field> CreateFieldDirect(
bool deprecated = false,
bool required = false,
bool key = false,
const std::vector<flatbuffers::Offset<KeyValue>> *attributes = nullptr) {
const std::vector<flatbuffers::Offset<KeyValue>> *attributes = nullptr,
const std::vector<flatbuffers::Offset<flatbuffers::String>> *documentation = nullptr) {
return reflection::CreateField(
_fbb,
name ? _fbb.CreateString(name) : 0,
Expand All @@ -564,7 +591,8 @@ inline flatbuffers::Offset<Field> CreateFieldDirect(
deprecated,
required,
key,
attributes ? _fbb.CreateVector<flatbuffers::Offset<KeyValue>>(*attributes) : 0);
attributes ? _fbb.CreateVector<flatbuffers::Offset<KeyValue>>(*attributes) : 0,
documentation ? _fbb.CreateVector<flatbuffers::Offset<flatbuffers::String>>(*documentation) : 0);
}

struct Object FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
Expand All @@ -574,7 +602,8 @@ struct Object FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
VT_IS_STRUCT = 8,
VT_MINALIGN = 10,
VT_BYTESIZE = 12,
VT_ATTRIBUTES = 14
VT_ATTRIBUTES = 14,
VT_DOCUMENTATION = 16
};
const flatbuffers::String *name() const {
return GetPointer<const flatbuffers::String *>(VT_NAME);
Expand All @@ -600,6 +629,9 @@ struct Object FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
const flatbuffers::Vector<flatbuffers::Offset<KeyValue>> *attributes() const {
return GetPointer<const flatbuffers::Vector<flatbuffers::Offset<KeyValue>> *>(VT_ATTRIBUTES);
}
const flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>> *documentation() const {
return GetPointer<const flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>> *>(VT_DOCUMENTATION);
}
bool Verify(flatbuffers::Verifier &verifier) const {
return VerifyTableStart(verifier) &&
VerifyFieldRequired<flatbuffers::uoffset_t>(verifier, VT_NAME) &&
Expand All @@ -613,6 +645,9 @@ struct Object FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
VerifyField<flatbuffers::uoffset_t>(verifier, VT_ATTRIBUTES) &&
verifier.Verify(attributes()) &&
verifier.VerifyVectorOfTables(attributes()) &&
VerifyField<flatbuffers::uoffset_t>(verifier, VT_DOCUMENTATION) &&
verifier.Verify(documentation()) &&
verifier.VerifyVectorOfStrings(documentation()) &&
verifier.EndTable();
}
};
Expand All @@ -638,13 +673,16 @@ struct ObjectBuilder {
void add_attributes(flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<KeyValue>>> attributes) {
fbb_.AddOffset(Object::VT_ATTRIBUTES, attributes);
}
void add_documentation(flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>>> documentation) {
fbb_.AddOffset(Object::VT_DOCUMENTATION, documentation);
}
ObjectBuilder(flatbuffers::FlatBufferBuilder &_fbb)
: fbb_(_fbb) {
start_ = fbb_.StartTable();
}
ObjectBuilder &operator=(const ObjectBuilder &);
flatbuffers::Offset<Object> Finish() {
const auto end = fbb_.EndTable(start_, 6);
const auto end = fbb_.EndTable(start_, 7);
auto o = flatbuffers::Offset<Object>(end);
fbb_.Required(o, Object::VT_NAME);
fbb_.Required(o, Object::VT_FIELDS);
Expand All @@ -659,8 +697,10 @@ inline flatbuffers::Offset<Object> CreateObject(
bool is_struct = false,
int32_t minalign = 0,
int32_t bytesize = 0,
flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<KeyValue>>> attributes = 0) {
flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<KeyValue>>> attributes = 0,
flatbuffers::Offset<flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>>> documentation = 0) {
ObjectBuilder builder_(_fbb);
builder_.add_documentation(documentation);
builder_.add_attributes(attributes);
builder_.add_bytesize(bytesize);
builder_.add_minalign(minalign);
Expand All @@ -677,15 +717,17 @@ inline flatbuffers::Offset<Object> CreateObjectDirect(
bool is_struct = false,
int32_t minalign = 0,
int32_t bytesize = 0,
const std::vector<flatbuffers::Offset<KeyValue>> *attributes = nullptr) {
const std::vector<flatbuffers::Offset<KeyValue>> *attributes = nullptr,
const std::vector<flatbuffers::Offset<flatbuffers::String>> *documentation = nullptr) {
return reflection::CreateObject(
_fbb,
name ? _fbb.CreateString(name) : 0,
fields ? _fbb.CreateVector<flatbuffers::Offset<Field>>(*fields) : 0,
is_struct,
minalign,
bytesize,
attributes ? _fbb.CreateVector<flatbuffers::Offset<KeyValue>>(*attributes) : 0);
attributes ? _fbb.CreateVector<flatbuffers::Offset<KeyValue>>(*attributes) : 0,
documentation ? _fbb.CreateVector<flatbuffers::Offset<flatbuffers::String>>(*documentation) : 0);
}

struct Schema FLATBUFFERS_FINAL_CLASS : private flatbuffers::Table {
Expand Down
3 changes: 3 additions & 0 deletions reflection/reflection.fbs
View file
Expand Up @@ -51,6 +51,7 @@ table Enum {
is_union:bool = false;
underlying_type:Type (required);
attributes:[KeyValue];
documentation:[string];
}

table Field {
Expand All @@ -64,6 +65,7 @@ table Field {
required:bool = false;
key:bool = false;
attributes:[KeyValue];
documentation:[string];
}

table Object { // Used for both tables and structs.
Expand All @@ -73,6 +75,7 @@ table Object { // Used for both tables and structs.
minalign:int;
bytesize:int; // For structs.
attributes:[KeyValue];
documentation:[string];
}

table Schema {
Expand Down
3 changes: 3 additions & 0 deletions src/flatc.cpp
View file
Expand Up @@ -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"
Expand Down Expand Up @@ -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 ||
Expand Down
16 changes: 13 additions & 3 deletions src/idl_parser.cpp
View file
Expand Up @@ -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,
Expand All @@ -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.
}
Expand All @@ -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
Expand Down
1 change: 1 addition & 0 deletions tests/generate_code.sh
View file
Expand Up @@ -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
Expand Down
Binary file modified tests/monster_test.bfbs
View file
Binary file not shown.

0 comments on commit 1fb6b9e

Please sign in to comment.