Output multiline doc comments over multiple lines

Tested: on Linux

Bug: 15779934
Change-Id: I6f822f1705e443d8721ea208dcb021aad3c8715c

include/flatbuffers/idl.h

@@ -178,7 +178,7 @@ struct Definition {
   Definition() : generated(false), defined_namespace(nullptr) {}
 
   std::string name;
-  std::string doc_comment;
+  std::vector<std::string> doc_comment;
   SymbolTable<Value> attributes;
   bool generated;  // did we already output code for this definition?
   Namespace *defined_namespace;  // Where it was defined.
@@ -234,7 +234,7 @@ struct EnumVal {
     : name(_name), value(_val), struct_def(nullptr) {}
 
   std::string name;
-  std::string doc_comment;
+  std::vector<std::string> doc_comment;
   int64_t value;
   StructDef *struct_def;  // only set if this is a union
 };
@@ -333,7 +333,8 @@ class Parser {
   const char *source_, *cursor_;
   int line_;  // the current line being parsed
   int token_;
-  std::string attribute_, doc_comment_;
+  std::string attribute_;
+  std::vector<std::string> doc_comment_;
 
   std::vector<std::pair<Value, FieldDef *>> field_stack_;
   std::vector<uint8_t> struct_stack_;
@@ -342,7 +343,8 @@ class Parser {
 // Utility functions for multiple generators:
 
 extern std::string MakeCamel(const std::string &in, bool first = true);
-extern void GenComment(const std::string &dc, std::string *code_ptr,
+extern void GenComment(const std::vector<std::string> &dc,
+                       std::string *code_ptr,
                        const char *prefix = "");
 
 // Container of options that may apply to any of the source/text generators.

src/idl_gen_general.cpp

@@ -38,11 +38,13 @@ std::string MakeCamel(const std::string &in, bool first) {
 }
 
 // Generate a documentation comment, if available.
-void GenComment(const std::string &dc, std::string *code_ptr,
+void GenComment(const std::vector<std::string> &dc, std::string *code_ptr,
                 const char *prefix) {
   std::string &code = *code_ptr;
-  if (dc.length()) {
-    code += std::string(prefix) + "///" + dc + "\n";
+  for (auto it = dc.begin();
+       it != dc.end();
+       ++it) {
+    code += std::string(prefix) + "///" + *it + "\n";
   }
 }
 

src/idl_gen_go.cpp

@@ -44,16 +44,6 @@ static std::string GenTypeGet(const Type &type);
 static std::string TypeName(const FieldDef &field);
 
 
-// Write a comment.
-static void Comment(const std::string &dc,
-                       std::string *code_ptr,
-                       const char *prefix = "") {
-  std::string &code = *code_ptr;
-  if (dc.length()) {
-    code += std::string(prefix) + "///" + dc + "\n";
-  }
-}
-
 // Most field accessors need to retrieve and test the field offset first,
 // this is the prefix code for that.
 std::string OffsetPrefix(const FieldDef &field) {
@@ -453,7 +443,7 @@ static void GenReceiver(const StructDef &struct_def, std::string *code_ptr) {
 static void GenStructAccessor(const StructDef &struct_def,
                               const FieldDef &field,
                               std::string *code_ptr) {
-  Comment(field.doc_comment, code_ptr, "");
+  GenComment(field.doc_comment, code_ptr, "");
   if (IsScalar(field.value.type.base_type)) {
     if (struct_def.fixed) {
       GetScalarFieldOfStruct(struct_def, field, code_ptr);
@@ -520,7 +510,7 @@ static void GenStruct(const StructDef &struct_def,
                       StructDef *root_struct_def) {
   if (struct_def.generated) return;
 
-  Comment(struct_def.doc_comment, code_ptr);
+  GenComment(struct_def.doc_comment, code_ptr);
   BeginClass(struct_def, code_ptr);
   if (&struct_def == root_struct_def) {
     // Generate a special accessor for the table that has been declared as
@@ -552,13 +542,13 @@ static void GenStruct(const StructDef &struct_def,
 static void GenEnum(const EnumDef &enum_def, std::string *code_ptr) {
   if (enum_def.generated) return;
 
-  Comment(enum_def.doc_comment, code_ptr);
+  GenComment(enum_def.doc_comment, code_ptr);
   BeginEnum(code_ptr);
   for (auto it = enum_def.vals.vec.begin();
        it != enum_def.vals.vec.end();
        ++it) {
     auto &ev = **it;
-    Comment(ev.doc_comment, code_ptr, "  ");
+    GenComment(ev.doc_comment, code_ptr, "\t");
     EnumMember(enum_def, ev, code_ptr);
   }
   EndEnum(code_ptr);

src/idl_parser.cpp

@@ -186,8 +186,7 @@ void Parser::Next() {
           if (*start == '/') {  // documentation comment
             if (!seen_newline)
               Error("a documentation comment should be on a line on its own");
-            // todo: do we want to support multiline comments instead?
-            doc_comment_ += std::string(start + 1, cursor_);
+            doc_comment_.push_back(std::string(start + 1, cursor_));
           }
           break;
         }
@@ -345,7 +344,7 @@ FieldDef &Parser::AddField(StructDef &struct_def,
 
 void Parser::ParseField(StructDef &struct_def) {
   std::string name = attribute_;
-  std::string dc = doc_comment_;
+  std::vector<std::string> dc = doc_comment_;
   Expect(kTokenIdentifier);
   Expect(':');
   Type type;
@@ -704,7 +703,7 @@ StructDef *Parser::LookupCreateStruct(const std::string &name) {
 }
 
 void Parser::ParseEnum(bool is_union) {
-  std::string dc = doc_comment_;
+  std::vector<std::string> dc = doc_comment_;
   Next();
   std::string name = attribute_;
   Expect(kTokenIdentifier);
@@ -734,7 +733,7 @@ void Parser::ParseEnum(bool is_union) {
   if (is_union) enum_def.vals.Add("NONE", new EnumVal("NONE", 0));
   do {
     std::string name = attribute_;
-    std::string dc = doc_comment_;
+    std::vector<std::string> dc = doc_comment_;
     Expect(kTokenIdentifier);
     auto prevsize = enum_def.vals.vec.size();
     auto value = enum_def.vals.vec.size()
@@ -767,7 +766,7 @@ void Parser::ParseEnum(bool is_union) {
 }
 
 void Parser::ParseDecl() {
-  std::string dc = doc_comment_;
+  std::vector<std::string> dc = doc_comment_;
   bool fixed = IsNext(kTokenStruct);
   if (!fixed) Expect(kTokenTable);
   std::string name = attribute_;

tests/MyGame/Example/Monster.cs

@@ -25,7 +25,8 @@ public class Monster : Table {
   public int Test4Length() { int o = __offset(22); return o != 0 ? __vector_len(o) : 0; }
   public string Testarrayofstring(int j) { int o = __offset(24); return o != 0 ? __string(__vector(o) + j * 4) : null; }
   public int TestarrayofstringLength() { int o = __offset(24); return o != 0 ? __vector_len(o) : 0; }
-  /// an example documentation comment: this will end up in the generated code multiline too
+  /// an example documentation comment: this will end up in the generated code
+  /// multiline too
   public Monster Testarrayoftables(int j) { return Testarrayoftables(new Monster(), j); }
   public Monster Testarrayoftables(Monster obj, int j) { int o = __offset(26); return o != 0 ? obj.__init(__indirect(__vector(o) + j * 4), bb) : null; }
   public int TestarrayoftablesLength() { int o = __offset(26); return o != 0 ? __vector_len(o) : 0; }

tests/MyGame/Example/Monster.go

@@ -139,7 +139,8 @@ func (rcv *Monster) TestarrayofstringLength() int {
 	return 0
 }
 
-/// an example documentation comment: this will end up in the generated code multiline too
+/// an example documentation comment: this will end up in the generated code
+/// multiline too
 func (rcv *Monster) Testarrayoftables(obj *Monster, j int) bool {
 	o := flatbuffers.UOffsetT(rcv._tab.Offset(26))
 	if o != 0 {

tests/MyGame/Example/Monster.java

@@ -31,7 +31,8 @@ public class Monster extends Table {
   public String testarrayofstring(int j) { int o = __offset(24); return o != 0 ? __string(__vector(o) + j * 4) : null; }
   public int testarrayofstringLength() { int o = __offset(24); return o != 0 ? __vector_len(o) : 0; }
   public ByteBuffer testarrayofstringAsByteBuffer() { return __vector_as_bytebuffer(24, 4); }
-  /// an example documentation comment: this will end up in the generated code multiline too
+  /// an example documentation comment: this will end up in the generated code
+  /// multiline too
   public Monster testarrayoftables(int j) { return testarrayoftables(new Monster(), j); }
   public Monster testarrayoftables(Monster obj, int j) { int o = __offset(26); return o != 0 ? obj.__init(__indirect(__vector(o) + j * 4), bb) : null; }
   public int testarrayoftablesLength() { int o = __offset(26); return o != 0 ? __vector_len(o) : 0; }

tests/monster_test_generated.h

@@ -96,7 +96,8 @@ struct Monster : private flatbuffers::Table {
   const void *test() const { return GetPointer<const void *>(20); }
   const flatbuffers::Vector<const Test *> *test4() const { return GetPointer<const flatbuffers::Vector<const Test *> *>(22); }
   const flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>> *testarrayofstring() const { return GetPointer<const flatbuffers::Vector<flatbuffers::Offset<flatbuffers::String>> *>(24); }
-  /// an example documentation comment: this will end up in the generated code multiline too
+  /// an example documentation comment: this will end up in the generated code
+  /// multiline too
   const flatbuffers::Vector<flatbuffers::Offset<Monster>> *testarrayoftables() const { return GetPointer<const flatbuffers::Vector<flatbuffers::Offset<Monster>> *>(26); }
   const Monster *enemy() const { return GetPointer<const Monster *>(28); }
   const flatbuffers::Vector<uint8_t> *testnestedflatbuffer() const { return GetPointer<const flatbuffers::Vector<uint8_t> *>(30); }