Fix multi-line comments for cpp enums (#5345) (#5346)

- fix CSharp comments generation
- fix Python comments generation
- fix Lua comments generation
- fix PHP comments generation
- fix Dart comments generation
- add brief description of Color enum
- add multi-line comments to the Monster:Color

src/idl_gen_cpp.cpp

@@ -948,7 +948,6 @@ class CppGenerator : public BaseGenerator {
   void GenEnum(const EnumDef &enum_def) {
     code_.SetValue("ENUM_NAME", Name(enum_def));
     code_.SetValue("BASE_TYPE", GenTypeBasic(enum_def.underlying_type, false));
-    code_.SetValue("SEP", "");
 
     GenComment(enum_def.doc_comment);
     code_ += GenEnumDecl(enum_def) + "\\";
@@ -961,19 +960,18 @@ class CppGenerator : public BaseGenerator {
     if (add_type) code_ += " : {{BASE_TYPE}}\\";
     code_ += " {";
 
+    code_.SetValue("SEP", ",");
+    auto add_sep = false;
     for (auto it = enum_def.Vals().begin(); it != enum_def.Vals().end(); ++it) {
       const auto &ev = **it;
-      if (!ev.doc_comment.empty()) {
-        auto prefix = code_.GetValue("SEP") + "  ";
-        GenComment(ev.doc_comment, prefix.c_str());
-        code_.SetValue("SEP", "");
-      }
+      if (add_sep) code_ += "{{SEP}}";
+      GenComment(ev.doc_comment, "  ");
       code_.SetValue("KEY", GenEnumValDecl(enum_def, Name(ev)));
       code_.SetValue("VALUE",
                      NumToStringCpp(enum_def.ToString(ev),
                                     enum_def.underlying_type.base_type));
-      code_ += "{{SEP}}  {{KEY}} = {{VALUE}}\\";
-      code_.SetValue("SEP", ",\n");
+      code_ += "  {{KEY}} = {{VALUE}}\\";
+      add_sep = true;
     }
     const EnumVal *minv = enum_def.MinValue();
     const EnumVal *maxv = enum_def.MaxValue();

src/idl_gen_dart.cpp

@@ -181,7 +181,6 @@ class DartGenerator : public BaseGenerator {
     }
 
     auto &code = *code_ptr;
-    if (indent) code += indent;
 
     for (auto it = dc.begin(); it != dc.end(); ++it) {
       if (indent) code += indent;
@@ -495,7 +494,7 @@ class DartGenerator : public BaseGenerator {
       std::string type_name = GenDartTypeName(
           field.value.type, struct_def.defined_namespace, field, false);
 
-      GenDocComment(field.doc_comment, &code, "");
+      GenDocComment(field.doc_comment, &code, "", "  ");
 
       code += "  " + type_name + " get " + field_name;
       if (field.value.type.base_type == BASE_TYPE_UNION) {

src/idl_gen_general.cpp

@@ -510,17 +510,17 @@ class GeneralGenerator : public BaseGenerator {
     std::string &code = *code_ptr;
     if (enum_def.generated) return;
 
-    // In C# this indicates enumeration values can be treated as bit flags.
-    if (lang_.language == IDLOptions::kCSharp && enum_def.attributes.Lookup("bit_flags")) {
-        code += "[System.FlagsAttribute]\n";
-    }
-
     // Generate enum definitions of the form:
     // public static (final) int name = value;
     // In Java, we use ints rather than the Enum feature, because we want them
     // to map directly to how they're used in C/C++ and file formats.
     // That, and Java Enums are expensive, and not universally liked.
     GenComment(enum_def.doc_comment, code_ptr, &lang_.comment_config);
+
+    // In C# this indicates enumeration values can be treated as bit flags.
+    if (lang_.language == IDLOptions::kCSharp && enum_def.attributes.Lookup("bit_flags")) {
+      code += "[System.FlagsAttribute]\n";
+    }
     if (enum_def.attributes.Lookup("private")) {
       // For Java, we leave the enum unmarked to indicate package-private
       // For C# we mark the enum as internal
@@ -547,7 +547,8 @@ class GeneralGenerator : public BaseGenerator {
         code += lang_.const_decl;
         code += GenTypeBasic(enum_def.underlying_type, false);
       }
-      code += " " + ev.name + " = ";
+      code += (lang_.language == IDLOptions::kJava) ? " " : "  ";
+      code += ev.name + " = ";
       code += enum_def.ToString(ev);
       code += lang_.enum_separator;
     }

src/idl_gen_lua.cpp

@@ -29,6 +29,7 @@ namespace flatbuffers {
 namespace lua {
 
   // Hardcode spaces per indentation.
+  const CommentConfig def_comment = { nullptr, "--", nullptr };
   const char * Indent = "    ";
   const char * Comment = "-- ";
   const char * End = "end\n";
@@ -472,7 +473,7 @@ namespace lua {
     // Generate a struct field, conditioned on its child type(s).
     void GenStructAccessor(const StructDef &struct_def,
       const FieldDef &field, std::string *code_ptr) {
-      GenComment(field.doc_comment, code_ptr, nullptr, Comment);
+      GenComment(field.doc_comment, code_ptr, &def_comment);
       if (IsScalar(field.value.type.base_type)) {
         if (struct_def.fixed) {
           GetScalarFieldOfStruct(struct_def, field, code_ptr);
@@ -535,7 +536,7 @@ namespace lua {
     void GenStruct(const StructDef &struct_def, std::string *code_ptr) {
       if (struct_def.generated) return;
 
-      GenComment(struct_def.doc_comment, code_ptr, nullptr, Comment);
+      GenComment(struct_def.doc_comment, code_ptr, &def_comment);
       BeginClass(struct_def, code_ptr);
 
       GenerateNewObjectPrototype(struct_def, code_ptr);
@@ -571,12 +572,12 @@ namespace lua {
     void GenEnum(const EnumDef &enum_def, std::string *code_ptr) {
       if (enum_def.generated) return;
 
-      GenComment(enum_def.doc_comment, code_ptr, nullptr, Comment);
+      GenComment(enum_def.doc_comment, code_ptr, &def_comment);
       BeginEnum(NormalizedName(enum_def), code_ptr);
       for (auto it = enum_def.Vals().begin(); it != enum_def.Vals().end();
            ++it) {
         auto &ev = **it;
-        GenComment(ev.doc_comment, code_ptr, nullptr, Comment);
+        GenComment(ev.doc_comment, code_ptr, &def_comment, Indent);
         EnumMember(enum_def, ev, code_ptr);
       }
       EndEnum(code_ptr);

src/idl_gen_php.cpp

@@ -673,7 +673,7 @@ class PhpGenerator : public BaseGenerator {
   // Generate a struct field, conditioned on its child type(s).
   void GenStructAccessor(const StructDef &struct_def, const FieldDef &field,
                          std::string *code_ptr) {
-    GenComment(field.doc_comment, code_ptr, nullptr);
+    GenComment(field.doc_comment, code_ptr, nullptr, Indent.c_str());
 
     if (IsScalar(field.value.type.base_type)) {
       if (struct_def.fixed) {
@@ -818,7 +818,7 @@ class PhpGenerator : public BaseGenerator {
     BeginEnum(enum_def.name, code_ptr);
     for (auto it = enum_def.Vals().begin(); it != enum_def.Vals().end(); ++it) {
       auto &ev = **it;
-      GenComment(ev.doc_comment, code_ptr, nullptr);
+      GenComment(ev.doc_comment, code_ptr, nullptr, Indent.c_str());
       EnumMember(enum_def, ev, code_ptr);
     }
 

src/idl_gen_python.cpp

@@ -29,6 +29,7 @@ namespace flatbuffers {
 namespace python {
 
 // Hardcode spaces per indentation.
+const CommentConfig def_comment = { nullptr, "#", nullptr };
 const std::string Indent = "    ";
 
 class PythonGenerator : public BaseGenerator {
@@ -497,7 +498,7 @@ class PythonGenerator : public BaseGenerator {
   // Generate a struct field, conditioned on its child type(s).
   void GenStructAccessor(const StructDef &struct_def,
                          const FieldDef &field, std::string *code_ptr) {
-    GenComment(field.doc_comment, code_ptr, nullptr, "# ");
+    GenComment(field.doc_comment, code_ptr, &def_comment, Indent.c_str());
     if (IsScalar(field.value.type.base_type)) {
       if (struct_def.fixed) {
         GetScalarFieldOfStruct(struct_def, field, code_ptr);
@@ -557,7 +558,7 @@ class PythonGenerator : public BaseGenerator {
   void GenStruct(const StructDef &struct_def, std::string *code_ptr) {
     if (struct_def.generated) return;
 
-    GenComment(struct_def.doc_comment, code_ptr, nullptr, "# ");
+    GenComment(struct_def.doc_comment, code_ptr, &def_comment);
     BeginClass(struct_def, code_ptr);
     if (!struct_def.fixed) {
       // Generate a special accessor for the table that has been declared as
@@ -588,11 +589,11 @@ class PythonGenerator : public BaseGenerator {
   void GenEnum(const EnumDef &enum_def, std::string *code_ptr) {
     if (enum_def.generated) return;
 
-    GenComment(enum_def.doc_comment, code_ptr, nullptr, "# ");
+    GenComment(enum_def.doc_comment, code_ptr, &def_comment);
     BeginEnum(NormalizedName(enum_def), code_ptr);
     for (auto it = enum_def.Vals().begin(); it != enum_def.Vals().end(); ++it) {
       auto &ev = **it;
-      GenComment(ev.doc_comment, code_ptr, nullptr, "# ");
+      GenComment(ev.doc_comment, code_ptr, &def_comment, Indent.c_str());
       EnumMember(enum_def, ev, code_ptr);
     }
     EndEnum(code_ptr);

tests/MyGame/Example/Any.cs

@@ -7,10 +7,10 @@ namespace MyGame.Example
 
 public enum Any : byte
 {
- NONE = 0,
- Monster = 1,
- TestSimpleTableWithEnum = 2,
- MyGame_Example2_Monster = 3,
+  NONE = 0,
+  Monster = 1,
+  TestSimpleTableWithEnum = 2,
+  MyGame_Example2_Monster = 3,
 };
 
 

tests/MyGame/Example/AnyAmbiguousAliases.cs

@@ -7,10 +7,10 @@ namespace MyGame.Example
 
 public enum AnyAmbiguousAliases : byte
 {
- NONE = 0,
- M1 = 1,
- M2 = 2,
- M3 = 3,
+  NONE = 0,
+  M1 = 1,
+  M2 = 2,
+  M3 = 3,
 };
 
 

tests/MyGame/Example/AnyUniqueAliases.cs

@@ -7,10 +7,10 @@ namespace MyGame.Example
 
 public enum AnyUniqueAliases : byte
 {
- NONE = 0,
- M = 1,
- TS = 2,
- M2 = 3,
+  NONE = 0,
+  M = 1,
+  TS = 2,
+  M2 = 3,
 };
 
 

tests/MyGame/Example/Color.cs

@@ -5,12 +5,16 @@
 namespace MyGame.Example
 {
 
+/// Composite components of Monster color.
 [System.FlagsAttribute]
 public enum Color : byte
 {
- Red = 1,
- Green = 2,
- Blue = 8,
+  Red = 1,
+  /// \brief color Green
+  /// Green is bit_flag with value (1u << 1)
+  Green = 2,
+  /// \brief color Blue (1u << 3)
+  Blue = 8,
 };
 
 

tests/MyGame/Example/Color.go

@@ -4,11 +4,15 @@ package Example
 
 import "strconv"
 
+/// Composite components of Monster color.
 type Color byte
 
 const (
 	ColorRed   Color = 1
+	/// \brief color Green
+	/// Green is bit_flag with value (1u << 1)
 	ColorGreen Color = 2
+	/// \brief color Blue (1u << 3)
 	ColorBlue  Color = 8
 )
 

tests/MyGame/Example/Color.java

@@ -2,10 +2,20 @@
 
 package MyGame.Example;
 
+/**
+ * Composite components of Monster color.
+ */
 public final class Color {
   private Color() { }
   public static final byte Red = 1;
+  /**
+   * \brief color Green
+   * Green is bit_flag with value (1u << 1)
+   */
   public static final byte Green = 2;
+  /**
+   * \brief color Blue (1u << 3)
+   */
   public static final byte Blue = 8;
 
   public static final String[] names = { "Red", "Green", "", "", "", "", "", "Blue", };

tests/MyGame/Example/Color.lua

@@ -2,9 +2,13 @@
 
 -- namespace: Example
 
+-- Composite components of Monster color.
 local Color = {
     Red = 1,
+    -- \brief color Green
+    -- Green is bit_flag with value (1u << 1)
     Green = 2,
+    -- \brief color Blue (1u << 3)
     Blue = 8,
 }
 

tests/MyGame/Example/Color.php

@@ -3,10 +3,14 @@
 
 namespace MyGame\Example;
 
+/// Composite components of Monster color.
 class Color
 {
     const Red = 1;
+    /// \brief color Green
+    /// Green is bit_flag with value (1u << 1)
     const Green = 2;
+    /// \brief color Blue (1u << 3)
     const Blue = 8;
 
     private static $names = array(

tests/MyGame/Example/Color.py

@@ -2,8 +2,12 @@
 
 # namespace: Example
 
+# Composite components of Monster color.
 class Color(object):
     Red = 1
+    # \brief color Green
+    # Green is bit_flag with value (1u << 1)
     Green = 2
+    # \brief color Blue (1u << 3)
     Blue = 8
 

tests/MyGame/Example/Monster.lua

@@ -4,7 +4,7 @@
 
 local flatbuffers = require('flatbuffers')
 
--- /// an example documentation comment: monster object
+-- an example documentation comment: monster object
 local Monster = {} -- the module
 local Monster_mt = {} -- the class metatable
 
@@ -120,8 +120,8 @@ function Monster_mt:TestarrayofstringLength()
     end
     return 0
 end
--- /// 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
 function Monster_mt:Testarrayoftables(j)
     local o = self.view:Offset(26)
     if o ~= 0 then

tests/MyGame/Example/Monster.php

@@ -171,8 +171,8 @@ class Monster extends Table
         return $o != 0 ? $this->__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
     /**
      * @returnVectorOffset
      */

tests/MyGame/Example/Monster.py

@@ -4,7 +4,7 @@
 
 import flatbuffers
 
-# /// an example documentation comment: monster object
+# an example documentation comment: monster object
 class Monster(object):
     __slots__ = ['_tab']
 
@@ -131,8 +131,8 @@ class Monster(object):
             return self._tab.VectorLen(o)
         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
     # Monster
     def Testarrayoftables(self, j):
         o = flatbuffers.number_types.UOffsetTFlags.py_type(self._tab.Offset(26))

tests/monster_test.fbs

@@ -14,7 +14,15 @@ namespace MyGame.Example;
 
 attribute "priority";
 
-enum Color:ubyte (bit_flags) { Red = 0, Green, Blue = 3, }
+/// Composite components of Monster color.
+enum Color:ubyte (bit_flags) { 
+  Red = 0, // color Red = (1u << 0)
+  /// \brief color Green
+  /// Green is bit_flag with value (1u << 1)
+  Green, 
+  /// \brief color Blue (1u << 3)
+  Blue = 3, 
+}
 
 union Any { Monster, TestSimpleTableWithEnum, MyGame.Example2.Monster }
 

tests/monster_test_generated.h

@@ -99,9 +99,13 @@ inline const flatbuffers::TypeTable *MonsterTypeTable();
 
 inline const flatbuffers::TypeTable *TypeAliasesTypeTable();
 
+/// Composite components of Monster color.
 enum Color {
   Color_Red = 1,
+  /// \brief color Green
+  /// Green is bit_flag with value (1u << 1)
   Color_Green = 2,
+  /// \brief color Blue (1u << 3)
   Color_Blue = 8,
   Color_NONE = 0,
   Color_ANY = 11

tests/monster_test_generated.js

@@ -25,20 +25,42 @@ MyGame.Example2 = MyGame.Example2 || {};
 MyGame.OtherNameSpace = MyGame.OtherNameSpace || {};
 
 /**
+ * Composite components of Monster color.
+ *
  * @enum {number}
  */
 MyGame.Example.Color = {
   Red: 1,
+
+  /**
+   * \brief color Green
+   * Green is bit_flag with value (1u << 1)
+   */
   Green: 2,
+
+  /**
+   * \brief color Blue (1u << 3)
+   */
   Blue: 8
 };
 
 /**
+ * Composite components of Monster color.
+ *
  * @enum {string}
  */
 MyGame.Example.ColorName = {
   1: 'Red',
+
+  /**
+   * \brief color Green
+   * Green is bit_flag with value (1u << 1)
+   */
   2: 'Green',
+
+  /**
+   * \brief color Blue (1u << 3)
+   */
   8: 'Blue'
 };
 

tests/monster_test_generated.lobster

@@ -3,9 +3,13 @@ import flatbuffers
 
 namespace MyGame_Example
 
+/// Composite components of Monster color.
 enum Color:
     Color_Red = 1
+    /// \brief color Green
+    /// Green is bit_flag with value (1u << 1)
     Color_Green = 2
+    /// \brief color Blue (1u << 3)
     Color_Blue = 8
 
 enum Any:

tests/monster_test_generated.rs

@@ -163,12 +163,16 @@ pub mod example {
   extern crate flatbuffers;
   use self::flatbuffers::EndianScalar;
 
+/// Composite components of Monster color.
 #[allow(non_camel_case_types)]
 #[repr(u8)]
 #[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
 pub enum Color {
   Red = 1,
+  /// \brief color Green
+  /// Green is bit_flag with value (1u << 1)
   Green = 2,
+  /// \brief color Blue (1u << 3)
   Blue = 8,
 
 }

tests/monster_test_generated.ts

 // automatically generated by the FlatBuffers compiler, do not modify
 
 /**
+ * Composite components of Monster color.
+ *
  * @enum {number}
  */
 export namespace MyGame.Example{
 export enum Color{
   Red= 1,
+
+  /**
+   * \brief color Green
+   * Green is bit_flag with value (1u << 1)
+   */
   Green= 2,
+
+  /**
+   * \brief color Blue (1u << 3)
+   */
   Blue= 8
 }};
 

tests/monster_test_my_game.example_generated.dart

@@ -9,6 +9,7 @@ import 'package:flat_buffers/flat_buffers.dart' as fb;
 import './monster_test_my_game_generated.dart' as my_game;
 import './monster_test_my_game.example2_generated.dart' as my_game_example2;
 
+///  Composite components of Monster color.
 class Color {
   final int value;
   const Color._(this.value);
@@ -24,7 +25,12 @@ class Color {
   static bool containsValue(int value) => values.containsKey(value);
 
   static const Color Red = const Color._(1);
+
+  ///  \brief color Green
+  ///  Green is bit_flag with value (1u << 1)
   static const Color Green = const Color._(2);
+
+  ///  \brief color Blue (1u << 3)
   static const Color Blue = const Color._(8);
   static get values => {1: Red,2: Green,8: Blue,};
 
@@ -700,8 +706,8 @@ class Monster {
   }
   List<Test> get test4 => const fb.ListReader<Test>(Test.reader).vTableGet(_bc, _bcOffset, 22, null);
   List<String> get testarrayofstring => const fb.ListReader<String>(const fb.StringReader()).vTableGet(_bc, _bcOffset, 24, null);
-///  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
   List<Monster> get testarrayoftables => const fb.ListReader<Monster>(Monster.reader).vTableGet(_bc, _bcOffset, 26, null);
   Monster get enemy => Monster.reader.vTableGet(_bc, _bcOffset, 28, null);
   List<int> get testnestedflatbuffer => const fb.ListReader<int>(const fb.Uint8Reader()).vTableGet(_bc, _bcOffset, 30, null);

tests/namespace_test/NamespaceA/NamespaceB/EnumInNestedNS.cs

@@ -7,9 +7,9 @@ namespace NamespaceA.NamespaceB
 
 public enum EnumInNestedNS : sbyte
 {
- A = 0,
- B = 1,
- C = 2,
+  A = 0,
+  B = 1,
+  C = 2,
 };
 
 

tests/union_vector/Character.cs

@@ -4,12 +4,12 @@
 
 public enum Character : byte
 {
- NONE = 0,
- MuLan = 1,
- Rapunzel = 2,
- Belle = 3,
- BookFan = 4,
- Other = 5,
- Unused = 6,
+  NONE = 0,
+  MuLan = 1,
+  Rapunzel = 2,
+  Belle = 3,
+  BookFan = 4,
+  Other = 5,
+  Unused = 6,
 };