【特性】支持comment属性，生成代码时包含类和字段注释

src/Luban.Job.Cfg/Source/Defs/CfgDefLoader.cs

@@ -152,7 +152,7 @@ namespace Luban.Job.Cfg.Defs
             _cfgServices.Add(new Service() { Name = name, Manager = manager, Groups = groups, Refs = refs });
         }
 
-        private readonly List<string> _tableOptionalAttrs = new List<string> { "index", "mode", "group", "branch_input" };
+        private readonly List<string> _tableOptionalAttrs = new List<string> { "index", "mode", "group", "branch_input", "comment" };
         private readonly List<string> _tableRequireAttrs = new List<string> { "name", "value", "input" };
 
 
@@ -224,6 +224,7 @@ namespace Luban.Job.Cfg.Defs
                 ValueType = XmlUtil.GetRequiredAttribute(e, "value"),
                 Index = XmlUtil.GetOptionalAttribute(e, "index"),
                 Groups = CreateGroups(XmlUtil.GetOptionalAttribute(e, "group")),
+                Comment = XmlUtil.GetOptionalAttribute(e, "comment"),
             };
             p.Mode = ConvertMode(p.Name, XmlUtil.GetOptionalAttribute(e, "mode"), p.Index);
 
@@ -267,7 +268,7 @@ namespace Luban.Job.Cfg.Defs
 
         private static readonly List<string> _fieldOptionalAttrs = new List<string> {
             "index", "sep", "validator", "key_validator", "value_validator",
-            "ref", "path", "range", "multi_rows", "group", "res", "convert" };
+            "ref", "path", "range", "multi_rows", "group", "res", "convert", "comment" };
 
         private static readonly List<string> _fieldRequireAttrs = new List<string> { "name", "type" };
 
@@ -283,6 +284,7 @@ namespace Luban.Job.Cfg.Defs
                 Groups = CreateGroups(XmlUtil.GetOptionalAttribute(e, "group")),
                 Resource = XmlUtil.GetOptionalAttribute(e, "res"),
                 Converter = XmlUtil.GetOptionalAttribute(e, "convert"),
+                Comment = XmlUtil.GetOptionalAttribute(e, "comment"),
             };
 
             // 字段与table的默认组不一样。
@@ -309,7 +311,7 @@ namespace Luban.Job.Cfg.Defs
             return f;
         }
 
-        private static readonly List<string> _beanOptinsAttrs = new List<string> { "value_type", "alias", "sep" };
+        private static readonly List<string> _beanOptinsAttrs = new List<string> { "value_type", "alias", "sep", "comment" };
         private static readonly List<string> _beanRequireAttrs = new List<string> { "name" };
 
         protected override void AddBean(XElement e, string parent)
@@ -326,6 +328,7 @@ namespace Luban.Job.Cfg.Defs
                 IsValueType = XmlUtil.GetOptionBoolAttribute(e, "value_type"),
                 Alias = XmlUtil.GetOptionalAttribute(e, "alias"),
                 Sep = XmlUtil.GetOptionalAttribute(e, "sep"),
+                Comment = XmlUtil.GetOptionalAttribute(e, "comment"),
             };
             var childBeans = new List<XElement>();
 

src/Luban.Job.Cfg/Source/Defs/DefTable.cs

@@ -20,6 +20,7 @@ namespace Luban.Job.Cfg.Defs
             InputFiles = b.InputFiles;
             Groups = b.Groups;
             _branchInputFiles = b.BranchInputFiles;
+            Comment = b.Comment;
         }
 
 

src/Luban.Job.Cfg/Source/Generate/CppCodeBinRender.cs

@@ -40,6 +40,9 @@ namespace Luban.Job.Cfg.Generate
     hierarchy_export_fields = x.hierarchy_export_fields
 }}
 
+/**
+{{x.comment}}
+ */
 class {{name}} : public {{if parent_def_type}} {{parent_def_type.cpp_full_name}} {{else}} bright::CfgBean {{end}}
 {
     public:
@@ -68,6 +71,9 @@ class {{name}} : public {{if parent_def_type}} {{parent_def_type.cpp_full_name}}
     bool deserialize(ByteBuf& _buf);
 
     {{~ for field in export_fields ~}}
+    /**
+     {{field.comment}}
+     */
     {{cpp_define_type field.ctype}} {{field.cpp_style_name}};
     {{~end~}}
 
@@ -102,6 +108,9 @@ class {{name}} : public {{if parent_def_type}} {{parent_def_type.cpp_full_name}}
     value_type =  x.value_ttype
 ~}}
 
+/**
+{{x.comment}}
+ */
 class {{name}}
 {
     {{~if x.is_map_table ~}}
@@ -151,7 +160,10 @@ class {{name}}
 
 
     {{~ for field in value_type.bean.hierarchy_export_fields ~}}
-     {{cpp_define_type field.ctype}}& {{field.cpp_getter_name}}() const { return _data->{{field.cpp_style_name}}; }
+    /**
+    {{field.comment}}
+     */
+    const {{cpp_define_type field.ctype}}& {{field.cpp_getter_name}}() const { return _data->{{field.cpp_style_name}}; }
     {{~end~}}
 
     {{~end~}}
@@ -172,6 +184,9 @@ class {{name}}
 {
     public:
     {{~for table in tables ~}}
+    /**
+     {{table.comment}}
+     */
      {{table.cpp_full_name}} {{table.name}};
     {{~end~}}
 

src/Luban.Job.Cfg/Source/Generate/CsCodeBinRender.cs

@@ -26,6 +26,9 @@ using System.Collections.Generic;
 namespace {{x.namespace_with_top_module}}
 {
 
+/// <summary>
+/// {{x.comment}}
+/// </summary>
 public {{x.cs_class_modifier}} partial class {{name}} : {{if parent_def_type}} {{x.parent}} {{else}} Bright.Config.BeanBase {{end}}
 {
     public {{name}}(ByteBuf _buf) {{if parent_def_type}} : base(_buf) {{end}}
@@ -70,6 +73,9 @@ public {{x.cs_class_modifier}} partial class {{name}} : {{if parent_def_type}} {
     }
 
     {{~ for field in export_fields ~}}
+    /// <summary>
+    /// {{field.comment}}
+    /// </summary>
     public readonly {{cs_define_type field.ctype}} {{field.cs_style_name}};
     {{~if field.index_field~}} 
     public readonly Dictionary<{{cs_define_type field.index_field.ctype}}, {{cs_define_type field.ctype.element_type}}> {{field.cs_style_name}}_Index = new Dictionary<{{cs_define_type field.index_field.ctype}}, {{cs_define_type field.ctype.element_type}}>();
@@ -136,6 +142,9 @@ namespace {{x.namespace_with_top_module}}
         key_type2 =  x.key_ttype2
         value_type =  x.value_ttype
     }}
+/// <summary>
+/// {{x.comment}}
+/// </summary>
 public sealed partial class {{name}}
 {
     {{~if x.is_map_table ~}}
@@ -189,6 +198,9 @@ public sealed partial class {{name}}
 
 
     {{~ for field in value_type.bean.hierarchy_export_fields ~}}
+    /// <summary>
+    /// {{field.comment}}
+    /// </summary>
      public {{cs_define_type field.ctype}} {{field.cs_style_name}} => _data.{{field.cs_style_name}};
     {{~if field.ref~}}
         public {{field.cs_ref_type_name}} {{field.cs_ref_var_name}} => _data.{{field.cs_ref_var_name}};
@@ -232,6 +244,9 @@ namespace {{namespace}}
 public sealed class {{name}}
 {
     {{~for table in tables ~}}
+    /// <summary>
+    /// {{table.comment}}
+    /// </summary>
     public {{table.full_name}} {{table.name}} {get; }
     {{~end~}}
 

src/Luban.Job.Cfg/Source/Generate/CsCodeJsonRender.cs

@@ -27,6 +27,9 @@ using System.Text.Json;
 namespace {{x.namespace_with_top_module}}
 {
 
+/// <summary>
+/// {{x.comment}}
+/// </summary>
 public {{x.cs_class_modifier}} partial class {{name}} : {{if parent_def_type}} {{parent}} {{else}} Bright.Config.BeanBase {{end}}
 {
     public {{name}}(JsonElement _buf) {{if parent_def_type}} : base(_buf) {{end}}
@@ -65,6 +68,9 @@ public {{x.cs_class_modifier}} partial class {{name}} : {{if parent_def_type}} {
     }
 
     {{~ for field in export_fields ~}}
+    /// <summary>
+    /// {{field.comment}}
+    /// </summary>
     public readonly {{cs_define_type field.ctype}} {{field.cs_style_name}};
     {{~if field.index_field~}} 
     public readonly Dictionary<{{cs_define_type field.index_field.ctype}}, {{cs_define_type field.ctype.element_type}}> {{field.cs_style_name}}_Index = new Dictionary<{{cs_define_type field.index_field.ctype}}, {{cs_define_type field.ctype.element_type}}>();
@@ -132,6 +138,10 @@ using System.Text.Json;
 
 namespace {{x.namespace_with_top_module}}
 {
+
+/// <summary>
+/// {{x.comment}}
+/// </summary>
 public sealed partial class {{name}}
 {
     {{~if x.is_map_table ~}}
@@ -183,6 +193,9 @@ public sealed partial class {{name}}
     }
 
     {{~ for field in value_type.bean.hierarchy_export_fields ~}}
+    /// <summary>
+    /// {{field.comment}}
+    /// </summary>
      public {{cs_define_type field.ctype}} {{field.cs_style_name}} => _data.{{field.cs_style_name}};
     {{~if field.ref~}}
         public {{field.cs_ref_type_name}} {{field.cs_ref_var_name}} => _data.{{field.cs_ref_var_name}};
@@ -226,6 +239,9 @@ namespace {{namespace}}
 public sealed partial class {{name}}
 {
     {{~for table in tables ~}}
+    /// <summary>
+    /// {{table.comment}}
+    /// </summary>
     public {{table.full_name}} {{table.name}} {get; }
     {{~end~}}
 

src/Luban.Job.Cfg/Source/Generate/JavaCodeBinRender.cs

@@ -26,6 +26,9 @@ import bright.serialization.*;
     hierarchy_export_fields = x.hierarchy_export_fields
 }}
 
+/**
+ * {{x.comment}}
+ */
 public {{x.java_class_modifier}} class {{name}} extends {{if parent_def_type}} {{x.parent_def_type.full_name_with_top_module}} {{else}} bright.serialization.AbstractBean {{end}}
 {
     public {{name}}(ByteBuf _buf)
@@ -76,6 +79,9 @@ public {{x.java_class_modifier}} class {{name}} extends {{if parent_def_type}} {
     }
 
     {{~ for field in export_fields ~}}
+    /**
+     * {{field.comment}}
+     */
     public final {{java_define_type field.ctype}} {{field.java_style_name}};
     {{~if field.index_field~}} 
     public final java.util.HashMap<{{java_box_define_type field.index_field.ctype}}, {{java_box_define_type field.ctype.element_type}}> {{field.java_style_name}}_Index = new java.util.HashMap<>();
@@ -152,6 +158,9 @@ import bright.serialization.*;
     value_type =  x.value_ttype
 ~}}
 
+/**
+ * {{x.comment}}
+ */
 public final class {{name}}
 {
     {{~if x.is_map_table ~}}
@@ -203,6 +212,9 @@ public final class {{name}}
 
 
     {{~ for field in value_type.bean.hierarchy_export_fields ~}}
+    /**
+     * {{field.comment}}
+     */
      public {{java_define_type field.ctype}} {{field.java_getter_name}}() { return _data.{{field.java_style_name}}; }
     {{~end~}}
 
@@ -235,6 +247,9 @@ public final class {{name}}
     }
 
     {{~for table in tables ~}}
+    /**
+     * {{table.comment}}
+     */
     public final {{table.full_name_with_top_module}} {{table.name}};
     {{~end~}}
 

src/Luban.Job.Cfg/Source/Generate/Python27CodeJsonRender.cs

@@ -23,6 +23,9 @@ namespace Luban.Job.Cfg.Generate
     hierarchy_export_fields = x.hierarchy_export_fields
 }}
 
+'''
+{{x.comment}}
+'''
 class {{name}} {{if parent_def_type}}({{parent_def_type.py_full_name}}){{end}}:
 {{~if x.is_abstract_type~}}
     _childrenTypes = None
@@ -75,7 +78,9 @@ class {{name}} {{if parent_def_type}}({{parent_def_type.py_full_name}}){{end}}:
     key_type2 =  x.key_ttype2
     value_type =  x.value_ttype
 }}
-
+'''
+{{x.comment}}
+'''
 class {{name}}:
     {{~if x.is_map_table ~}}
 
@@ -102,6 +107,9 @@ class {{name}}:
     def getData(self) : return self._data
 
     {{~ for field in value_type.bean.hierarchy_export_fields ~}}
+    '''
+    {{field.comment}}
+    '''
     def {{field.py_style_name}}(self) : return self._data.{{field.py_style_name}}
     {{~end~}}
     {{~end~}}

src/Luban.Job.Cfg/Source/Generate/Python3CodeJsonRender.cs

@@ -101,6 +101,9 @@ class {{name}}:
     def getData(self) : return self._data
 
     {{~ for field in value_type.bean.hierarchy_export_fields ~}}
+    '''
+    {{field.comment}}
+    '''
     def {{field.py_style_name}}(self) : return self._data.{{field.py_style_name}}
     {{~end~}}
     {{~end~}}

src/Luban.Job.Cfg/Source/Generate/PythonCodeRenderBase.cs

@@ -21,9 +21,14 @@ namespace Luban.Job.Cfg.Generate
 
 
             var template = t_tsConstRender ??= Template.Parse(@"
-
+'''
+{{x.comment}}
+'''
 class {{x.py_full_name}}:
     {{~ for item in x.items ~}}
+    '''
+    {{item.comment}}
+    '''
     {{item.name}} = {{py_const_value item.ctype item.value}}
     {{~end~}}
     {{~if (x.items == empty)~}}
@@ -41,8 +46,14 @@ class {{x.py_full_name}}:
         public override string Render(DefEnum e)
         {
             var template = t_tsEnumRender ??= Template.Parse(@"
+'''
+{{comment}}
+'''
 class {{py_full_name}}:
     {{~ for item in items ~}}
+    '''
+    {{item.comment}}
+    '''
     {{item.name}} = {{item.value}}
     {{~end~}}
     {{~if (items == empty)~}}

src/Luban.Job.Cfg/Source/Generate/TypescriptCodeBinRender.cs

@@ -23,7 +23,9 @@ namespace Luban.Job.Cfg.Generate
 }}
 
 {{x.typescript_namespace_begin}}
-
+/**
+ * {{x.comment}}
+ */
 export {{if x.is_abstract_type}} abstract {{end}} class {{name}} {{if parent_def_type}} extends {{x.parent}}{{end}} {
 {{~if x.is_abstract_type~}}
     static constructorFrom(_buf_: ByteBuf): {{name}} {
@@ -46,6 +48,9 @@ export {{if x.is_abstract_type}} abstract {{end}} class {{name}} {{if parent_def
     }
 
     {{~ for field in export_fields ~}}
+    /**
+     * {{field.comment}}
+     */
     readonly {{field.ts_style_name}}{{if field.is_nullable}}?{{end}}: {{ts_define_type field.ctype}}
     {{~if field.gen_ref~}}
     {{field.ts_ref_validator_define}}
@@ -86,6 +91,9 @@ export {{if x.is_abstract_type}} abstract {{end}} class {{name}} {{if parent_def
         value_type =  x.value_ttype
     }}
 {{x.typescript_namespace_begin}}
+/**
+ * {{x.comment}}
+ */
 export class {{name}} {
     {{~if x.is_map_table ~}}
     private _dataMap: Map<{{ts_define_type key_type}}, {{ts_define_type value_type}}>
@@ -126,6 +134,9 @@ export class {{name}} {
     getData(): {{ts_define_type value_type}} { return this._data }
 
     {{~ for field in value_type.bean.hierarchy_export_fields ~}}
+    /**
+     * {{field.comment}}
+     */
      get {{field.ts_style_name}}(): {{ts_define_type field.ctype}} { return this._data.{{field.ts_style_name}} }
     {{~end~}}
 
@@ -159,6 +170,9 @@ type ByteBufLoader = (file: string) => ByteBuf
 export class {{name}} {
     {{~ for table in tables ~}}
     private _{{table.name}}: {{table.full_name}}
+    /**
+     * {{table.comment}}
+     */
     get {{table.name}}(): {{table.full_name}}  { return this._{{table.name}}}
     {{~end~}}
 

src/Luban.Job.Cfg/Source/Generate/TypescriptCodeJsonRender.cs

@@ -23,7 +23,9 @@ namespace Luban.Job.Cfg.Generate
 }}
 
 {{x.typescript_namespace_begin}}
-
+/**
+ * {{x.comment}}
+ */
 export {{if x.is_abstract_type}} abstract {{end}} class {{name}} {{if parent_def_type}} extends {{x.parent}}{{end}} {
 {{~if x.is_abstract_type~}}
     static constructorFrom(_json_: any): {{name}} {
@@ -49,6 +51,9 @@ export {{if x.is_abstract_type}} abstract {{end}} class {{name}} {{if parent_def
     }
 
     {{~ for field in export_fields ~}}
+    /**
+     * {{field.comment}}
+     */
     readonly {{field.ts_style_name}}{{if field.is_nullable}}?{{end}}: {{ts_define_type field.ctype}}
     {{~if field.gen_ref~}}
     {{field.ts_ref_validator_define}}
@@ -89,6 +94,9 @@ export {{if x.is_abstract_type}} abstract {{end}} class {{name}} {{if parent_def
         value_type =  x.value_ttype
     }}
 {{x.typescript_namespace_begin}}
+/**
+ * {{x.comment}}
+ */
 export class {{name}}{
     {{~if x.is_map_table ~}}
     private _dataMap: Map<{{ts_define_type key_type}}, {{ts_define_type value_type}}>
@@ -126,6 +134,9 @@ export class {{name}}{
     getData(): {{ts_define_type value_type}} { return this._data; }
 
     {{~ for field in value_type.bean.hierarchy_export_fields ~}}
+    /**
+     * {{field.comment}}
+     */
      get  {{field.ts_style_name}}(): {{ts_define_type field.ctype}} { return this._data.{{field.ts_style_name}}; }
     {{~end~}}
 
@@ -159,6 +170,9 @@ type JsonLoader = (file: string) => any
 export class {{name}} {
     {{~ for table in tables ~}}
     private _{{table.name}}: {{table.full_name}}
+    /**
+     * {{table.comment}}
+     */
     get {{table.name}}(): {{table.full_name}}  { return this._{{table.name}};}
     {{~end~}}
 

src/Luban.Job.Cfg/Source/RawDefs/Table.cs

@@ -31,6 +31,8 @@ namespace Luban.Job.Cfg.RawDefs
 
         public ETableMode Mode { get; set; }
 
+        public string Comment { get; set; }
+
         public List<string> Groups { get; set; } = new List<string>();
 
         public List<string> InputFiles { get; set; } = new List<string>();

src/Luban.Job.Common/Source/Defs/CommonDefLoader.cs

@@ -195,7 +195,7 @@ namespace Luban.Job.Common.Defs
         }
 
         private static readonly List<string> _fieldRequireAttrs = new List<string> { "name", "type", };
-        private static readonly List<string> _fieldOptionalAttrs = new List<string> { "id", };
+        private static readonly List<string> _fieldOptionalAttrs = new List<string> { "id", "comment" };
 
         protected virtual Field CreateField(XElement e)
         {
@@ -205,6 +205,7 @@ namespace Luban.Job.Common.Defs
                 Id = XmlUtil.GetOptionIntAttribute(e, "id"),
                 Name = XmlUtil.GetRequiredAttribute(e, "name"),
                 Type = CreateType(e, "type"),
+                Comment = XmlUtil.GetOptionalAttribute(e, "comment"),
             };
             return f;
         }
@@ -214,10 +215,10 @@ namespace Luban.Job.Common.Defs
             AddBean(e, "");
         }
 
-        private static readonly List<string> _beanOptinsAttrs1 = new List<string> { "compatible", "value_type" };
+        private static readonly List<string> _beanOptinsAttrs1 = new List<string> { "compatible", "value_type", "comment" };
         private static readonly List<string> _beanRequireAttrs1 = new List<string> { "id", "name" };
 
-        private static readonly List<string> _beanOptinsAttrs2 = new List<string> { "id", "compatible", "value_type" };
+        private static readonly List<string> _beanOptinsAttrs2 = new List<string> { "id", "compatible", "value_type", "comment" };
         private static readonly List<string> _beanRequireAttrs2 = new List<string> { "name" };
 
         protected virtual void AddBean(XElement e, string parent)
@@ -238,6 +239,7 @@ namespace Luban.Job.Common.Defs
                 TypeId = XmlUtil.GetOptionIntAttribute(e, "id"),
                 IsSerializeCompatible = XmlUtil.GetOptionBoolAttribute(e, "compatible", IsBeanDefaultCompatible),
                 IsValueType = XmlUtil.GetOptionBoolAttribute(e, "value_type"),
+                Comment = XmlUtil.GetOptionalAttribute(e, "comment"),
             };
             var childBeans = new List<XElement>();
 
@@ -303,34 +305,40 @@ namespace Luban.Job.Common.Defs
 
 
         private static readonly List<string> _constRequiredAttrs = new List<string> { "name" };
-        private static readonly List<string> _constOptionalItemAttrs = new List<string> { "value" };
+        private static readonly List<string> _constOptionalAttrs = new List<string> { "comment" };
+
         private static readonly List<string> _constItemRequiredAttrs = new List<string> { "name", "type" };
+        private static readonly List<string> _constItemOptionalAttrs = new List<string> { "value", "comment" };
 
         protected void AddConst(XElement e)
         {
-            ValidAttrKeys(e, null, _constRequiredAttrs);
+            ValidAttrKeys(e, _constOptionalAttrs, _constRequiredAttrs);
             var c = new Const()
             {
                 Name = XmlUtil.GetRequiredAttribute(e, "name"),
                 Namespace = CurNamespace,
+                Comment = XmlUtil.GetOptionalAttribute(e, "comment"),
             };
             foreach (XElement item in e.Elements())
             {
-                ValidAttrKeys(item, _constOptionalItemAttrs, _constItemRequiredAttrs);
+                ValidAttrKeys(item, _constItemOptionalAttrs, _constItemRequiredAttrs);
                 c.Items.Add(new ConstItem()
                 {
                     Name = XmlUtil.GetRequiredAttribute(item, "name"),
                     Type = CreateType(item, "type"),
                     Value = XmlUtil.GetRequiredAttribute(item, "value"),
+                    Comment = XmlUtil.GetOptionalAttribute(item, "comment"),
                 });
             }
             s_logger.Trace("add const {@const}", c);
             _consts.Add(c);
         }
 
-        private static readonly List<string> _enumOptionalAttrs = new List<string> { "flags" };
+        private static readonly List<string> _enumOptionalAttrs = new List<string> { "flags", "comment" };
         private static readonly List<string> _enumRequiredAttrs = new List<string> { "name" };
-        private static readonly List<string> _enumOptionalItemAttrs = new List<string> { "value", "alias" };
+
+
+        private static readonly List<string> _enumItemOptionalAttrs = new List<string> { "value", "alias", "comment" };
         private static readonly List<string> _enumItemRequiredAttrs = new List<string> { "name" };
 
         protected void AddEnum(XElement e)
@@ -340,17 +348,19 @@ namespace Luban.Job.Common.Defs
             {
                 Name = XmlUtil.GetRequiredAttribute(e, "name"),
                 Namespace = CurNamespace,
+                Comment = XmlUtil.GetOptionalAttribute(e, "comment"),
                 IsFlags = XmlUtil.GetOptionBoolAttribute(e, "flags"),
             };
 
             foreach (XElement item in e.Elements())
             {
-                ValidAttrKeys(item, _enumOptionalItemAttrs, _enumItemRequiredAttrs);
+                ValidAttrKeys(item, _enumItemOptionalAttrs, _enumItemRequiredAttrs);
                 en.Items.Add(new EnumItem()
                 {
                     Name = XmlUtil.GetRequiredAttribute(item, "name"),
                     Alias = XmlUtil.GetOptionalAttribute(item, "alias"),
                     Value = XmlUtil.GetOptionalAttribute(item, "value"),
+                    Comment = XmlUtil.GetOptionalAttribute(item, "comment"),
                 });
             }
             s_logger.Trace("add enum:{@enum}", en);

src/Luban.Job.Common/Source/Defs/DefBeanBase.cs

@@ -49,6 +49,7 @@ namespace Luban.Job.Common.Defs
             Parent = b.Parent;
             Id = b.TypeId;
             IsValueType = b.IsValueType;
+            Comment = b.Comment;
             foreach (var field in b.Fields)
             {
                 Fields.Add(CreateField(field, 0));

src/Luban.Job.Common/Source/Defs/DefConst.cs

@@ -16,6 +16,8 @@ namespace Luban.Job.Common.Defs
             public string Value { get; set; }
 
             public TType CType { get; set; }
+
+            public string Comment { get; set; }
         }
 
         public List<Item> Items { get; set; } = new List<Item>();
@@ -24,10 +26,11 @@ namespace Luban.Job.Common.Defs
         {
             Namespace = c.Namespace;
             Name = c.Name;
+            Comment = c.Comment;
 
             foreach (var item in c.Items)
             {
-                Items.Add(new Item { Name = item.Name, Type = item.Type, Value = item.Value });
+                Items.Add(new Item { Name = item.Name, Type = item.Type, Value = item.Value, Comment = item.Comment });
             }
         }
 

src/Luban.Job.Common/Source/Defs/DefEnum.cs

@@ -10,15 +10,17 @@ namespace Luban.Job.Common.Defs
     {
         public class Item
         {
-            public string Name { get; set; }
+            public string Name { get; init; }
 
             public string Value { get; set; }
 
-            public string Alias { get; set; }
+            public string Alias { get; init; }
 
             public string AliasOrName => string.IsNullOrWhiteSpace(Alias) ? Name : Alias;
 
             public int IntValue { get; set; }
+
+            public string Comment { get; init; }
         }
 
         public bool IsFlags { get; set; }
@@ -68,10 +70,11 @@ namespace Luban.Job.Common.Defs
             Namespace = e.Namespace;
             IsFlags = e.IsFlags;
             IsUniqueItemId = e.IsUniqueItemId;
+            Comment = e.Comment;
 
             foreach (var item in e.Items)
             {
-                Items.Add(new Item { Name = item.Name, Alias = item.Alias, Value = item.Value });
+                Items.Add(new Item { Name = item.Name, Alias = item.Alias, Value = item.Value, Comment = item.Comment });
             }
         }
 

src/Luban.Job.Common/Source/Defs/DefFieldBase.cs

@@ -69,12 +69,15 @@ namespace Luban.Job.Common.Defs
 
         public string UpperCaseName => Name.ToUpper();
 
+        public string Comment { get; }
+
         public DefFieldBase(DefTypeBase host, Field f, int idOffset)
         {
             HostType = host;
             Id = f.Id + idOffset;
             Name = f.Name;
             Type = f.Type;
+            Comment = f.Comment;
         }
 
         public virtual void Compile()

src/Luban.Job.Common/Source/Defs/DefTypeBase.cs

@@ -41,6 +41,8 @@ namespace Luban.Job.Common.Defs
 
         public string PyFullName => TypeUtil.MakePyFullName(Namespace, Name);
 
+        public string Comment { get; protected set; }
+
         public virtual void PreCompile() { }
 
         public abstract void Compile();

src/Luban.Job.Common/Source/RawDefs/Bean.cs

@@ -18,6 +18,8 @@ namespace Luban.Job.Common.RawDefs
 
         public bool IsSerializeCompatible { get; set; }
 
+        public string Comment { get; set; }
+
         public List<Field> Fields { get; set; } = new List<Field>();
     }
 }

src/Luban.Job.Common/Source/RawDefs/Const.cs

@@ -9,6 +9,8 @@ namespace Luban.Job.Common.RawDefs
         public string Type { get; set; }
 
         public string Value { get; set; }
+
+        public string Comment { get; set; }
     }
 
     public class Const
@@ -18,6 +20,8 @@ namespace Luban.Job.Common.RawDefs
 
         public string Name { get; set; }
 
+        public string Comment { get; set; }
+
         public List<ConstItem> Items { get; set; } = new List<ConstItem>();
     }
 }

src/Luban.Job.Common/Source/RawDefs/Field.cs

@@ -8,5 +8,7 @@ namespace Luban.Job.Common.RawDefs
         public string Name { get; set; }
 
         public string Type { get; set; }
+
+        public string Comment { get; set; }
     }
 }

src/Luban.Job.Common/Source/RawDefs/PEnum.cs

@@ -9,6 +9,8 @@ namespace Luban.Job.Common.RawDefs
         public string Alias { get; set; }
 
         public string Value { get; set; }
+
+        public string Comment { get; set; }
     }
 
     public class PEnum
@@ -22,6 +24,8 @@ namespace Luban.Job.Common.RawDefs
 
         public bool IsUniqueItemId { get; set; }
 
+        public string Comment { get; set; }
+
         public List<EnumItem> Items { get; set; } = new List<EnumItem>();
     }
 }

src/Luban.Job.Common/Source/Utils/RenderUtil.cs

@@ -21,10 +21,15 @@ namespace Luban.Job.Common.Utils
             var template = t_constRender ??= Template.Parse(@"
 namespace {{x.namespace_with_top_module}}
 {
-   
+    /// <summary>
+    /// {{x.comment}}
+    /// </summary>
     public sealed class {{x.name}}
     {
         {{~ for item in x.items ~}}
+        /// <summary>
+        /// {{item.comment}}
+        /// </summary>
         public const {{cs_define_type item.ctype}} {{item.name}} = {{cs_const_value item.ctype item.value}};
         {{~end~}}
     }
@@ -43,12 +48,18 @@ namespace {{x.namespace_with_top_module}}
             var template = t_enumRender ??= Template.Parse(@"
 namespace {{namespace_with_top_module}}
 {
+    /// <summary>
+    /// {{comment}}
+    /// </summary>
     {{~if is_flags~}}
     [System.Flags]
     {{~end~}}
     public enum {{name}}
     {
         {{~ for item in items ~}}
+        /// <summary>
+        /// {{item.comment}}
+        /// </summary>
         {{item.name}} = {{item.value}},
         {{~end~}}
     }
@@ -76,9 +87,15 @@ namespace {{namespace_with_top_module}}
             var template = t_javaConstRender ??= Template.Parse(@"
 package {{x.namespace_with_top_module}};
 
+/**
+ * {{x.comment}}
+ */
 public final class {{x.name}}
 {
     {{~ for item in x.items ~}}
+    /**
+     * {{item.comment}}
+     */
     public static final {{java_define_type item.ctype}} {{item.name}} = {{java_const_value item.ctype item.value}};
     {{~end~}}
 }
@@ -96,10 +113,15 @@ public final class {{x.name}}
         {
             var template = t_javaEnumRender ??= Template.Parse(@"
 package {{namespace_with_top_module}};
-
+/**
+ * {{comment}}
+ */
 public enum {{name}}
 {
     {{~ for item in items ~}}
+    /**
+     * {{item.comment}}
+     */
     {{item.name}}({{item.value}}),
     {{~end~}}
     ;
@@ -141,10 +163,15 @@ public enum {{name}}
 
             var template = t_cppConstRender ??= Template.Parse(@"
 {{x.cpp_namespace_begin}}
-
+/**
+{{x.comment}}
+*/
 struct {{x.name}}
 {
     {{~ for item in x.items ~}}
+    /**
+    {{item.comment}}
+    */
     static constexpr {{cpp_define_type item.ctype}} {{item.name}} = {{cpp_const_value item.ctype item.value}};
     {{~end~}}
 };
@@ -162,10 +189,15 @@ struct {{x.name}}
         {
             var template = t_cppEnumRender ??= Template.Parse(@"
 {{cpp_namespace_begin}}
-
+/**
+{{comment}}
+*/
 enum class {{name}}
 {
     {{~ for item in items ~}}
+    /**
+    {{item.comment}}
+    */
     {{item.name}} = {{item.value}},
     {{~end~}}
 };
@@ -191,9 +223,14 @@ enum class {{name}}
 
             var template = t_tsConstRender ??= Template.Parse(@"
 {{x.typescript_namespace_begin}}
-
+/**
+ * {{x.comment}}
+ */
 export class {{x.name}} {
     {{~ for item in x.items ~}}
+    /**
+     * {{item.comment}}
+     */
     static {{item.name}} = {{ts_const_value item.ctype item.value}};
     {{~end~}}
 }
@@ -211,9 +248,14 @@ export class {{x.name}} {
         {
             var template = t_tsEnumRender ??= Template.Parse(@"
 {{typescript_namespace_begin}}
-
+/**
+ * {{comment}}
+ */
 export enum {{name}} {
     {{~for item in items ~}}
+    /**
+     * {{item.comment}}
+     */
     {{item.name}} = {{item.value}},
     {{~end~}}
 }

src/Luban.Job.Db/Source/Defs/DbDefLoader.cs

@@ -33,7 +33,7 @@ namespace Luban.Job.Db.Defs
 
 
 
-        private readonly List<string> _tableOptionalAttrs = new List<string> { "memory" };
+        private readonly List<string> _tableOptionalAttrs = new List<string> { "memory", "comment" };
         private readonly List<string> _tableRequireAttrs = new List<string> { "name", "id", "key", "value" };
 
         private void AddTable(XElement e)
@@ -47,6 +47,7 @@ namespace Luban.Job.Db.Defs
                 KeyType = XmlUtil.GetRequiredAttribute(e, "key"),
                 ValueType = XmlUtil.GetRequiredAttribute(e, "value"),
                 IsPersistent = !XmlUtil.GetOptionBoolAttribute(e, "memory"),
+                Comment = XmlUtil.GetOptionalAttribute(e, "comment"),
             };
 
             s_logger.Trace("add Db:{@Db}", p);

src/Luban.Job.Db/Source/Defs/DefTable.cs

@@ -44,6 +44,11 @@ namespace Luban.Job.Db.Defs
                 throw new Exception($"table:{FullName} key:{KeyType} 类型不合法");
             }
 
+            if (!(KeyTType is TLong) && !(KeyTType is TString))
+            {
+                throw new Exception($"table:{FullName} key:{KeyTType} 不支持。只支持long与string类型");
+            }
+
             if ((ValueTType = (TBean)ass.CreateType(Namespace, ValueType)) == null)
             {
                 throw new Exception($"table:{FullName} value:{ValueType} 类型不合法");

src/Luban.Job.Db/Source/Generate/AsyncCsRender.cs

@@ -49,6 +49,9 @@ using Bright.Serialization;
 namespace {{x.namespace_with_top_module}}
 {
 
+/// <summary>
+/// {{x.comment}}
+/// </summary>
 public {{x.cs_class_modifier}} class {{name}} : {{if parent_def_type}} {{x.parent}} {{else}} Bright.Transaction.TxnBeanBase {{end}}
 {
     {{~ for field in fields~}}
@@ -81,6 +84,9 @@ public {{x.cs_class_modifier}} class {{name}} : {{if parent_def_type}} {{x.paren
         }
     }
 
+    /// <summary>
+    /// {{field.comment}}
+    /// </summary>
     public {{db_cs_define_type field.ctype}} {{field.cs_style_name}}
     { 
         get
@@ -139,7 +145,9 @@ public {{x.cs_class_modifier}} class {{name}} : {{if parent_def_type}} {{x.paren
             }
         }
             {{~end~}}
-
+    /// <summary>
+    /// {{field.comment}}
+    /// </summary>
     public {{db_cs_define_type field.ctype}} {{field.cs_style_name}} => {{field.internal_name}};
         {{~end~}}
     {{~end~}}
@@ -236,6 +244,9 @@ using System.Threading.Tasks;
 namespace {{x.namespace_with_top_module}}
 {
 
+/// <summary>
+/// {{x.comment}}
+/// </summary>
 public sealed class {{name}}
 {
     public static {{base_table_type}} Table { get; } = new {{internal_table_type}}();

src/Luban.Job.Db/Source/Generate/SyncCsRender.cs

@@ -50,6 +50,9 @@ using Bright.Serialization;
 namespace {{x.namespace_with_top_module}}
 {
 
+/// <summary>
+/// {{x.comment}}
+/// </summary>
 public interface {{readonly_name}} {{if parent_def_type}}: IReadOnly{{x.parent_def_type.name}} {{end}}
 {
     {{~ for field in fields~}}
@@ -57,6 +60,9 @@ public interface {{readonly_name}} {{if parent_def_type}}: IReadOnly{{x.parent_d
     {{~end~}}
 }
 
+/// <summary>
+/// {{x.comment}}
+/// </summary>
 public {{x.cs_class_modifier}} class {{name}} : {{if parent_def_type}} {{x.parent}} {{else}} Bright.Transaction.TxnBeanBase {{end}}, {{readonly_name}}
 {
     {{~ for field in fields~}}
@@ -91,6 +97,9 @@ public {{x.cs_class_modifier}} class {{name}} : {{if parent_def_type}} {{x.paren
         }
     }
 
+    /// <summary>
+    /// {{field.comment}}
+    /// </summary>
     public {{db_cs_define_type ctype}} {{field.cs_style_name}}
     { 
         get
@@ -127,12 +136,21 @@ public {{x.cs_class_modifier}} class {{name}} : {{if parent_def_type}} {{x.paren
         }
     }
         {{~else~}}
+        /// <summary>
+        /// {{field.comment}}
+        /// </summary>
          public {{db_cs_define_type ctype}} {{field.cs_style_name}} => {{field.internal_name}};
         {{~end~}}
 
         {{~if ctype.bean || ctype.element_type ~}}
+        /// <summary>
+        /// {{field.comment}}
+        /// </summary>
         {{db_cs_readonly_define_type ctype}} {{readonly_name}}.{{field.cs_style_name}} => {{field.internal_name}};
         {{~else if ctype.is_map~}}
+        /// <summary>
+        /// {{field.comment}}
+        /// </summary>
         {{db_cs_readonly_define_type ctype}} {{readonly_name}}.{{field.cs_style_name}} => new Bright.Transaction.Collections.PReadOnlyMap<{{db_cs_readonly_define_type ctype.key_type}}, {{db_cs_readonly_define_type ctype.value_type}}, {{db_cs_define_type ctype.value_type}}>({{field.internal_name}});
         {{~end~}}
     {{~end~}}
@@ -231,6 +249,9 @@ using System.Threading.Tasks;
 namespace {{x.namespace_with_top_module}}
 {
 
+/// <summary>
+/// {{x.comment}}
+/// </summary>
 public sealed class {{name}}
 {
     public static {{base_table_type}} Table { get; } = new {{internal_table_type}}();

src/Luban.Job.Db/Source/Generate/TypescriptRender.cs

@@ -49,8 +49,14 @@ namespace Luban.Job.Db.Generate
 }}
 
 {{x.typescript_namespace_begin}}
+/**
+ * {{x.comment}}
+ */
 export {{x.ts_class_modifier}} class {{name}} extends {{if parent_def_type}} {{x.parent}} {{else}} TxnBeanBase {{end}}{
     {{~ for field in fields~}}
+    /**
+     * {{field.comment}}
+     */
     {{if is_abstract_type}}protected{{else}}private{{end}} {{field.internal_name}}: {{db_ts_define_type field.ctype}} 
     {{~end}}
 
@@ -78,6 +84,9 @@ export {{x.ts_class_modifier}} class {{name}} extends {{if parent_def_type}} {{x
         }
     }
 
+    /**
+     * {{field.comment}}
+     */
     get {{field.ts_style_name}}(): {{db_ts_define_type ctype}} {
         if (this.isManaged) {
             var txn = TransactionContext.current
@@ -89,6 +98,9 @@ export {{x.ts_class_modifier}} class {{name}} extends {{if parent_def_type}} {{x
         }
     }
 
+    /**
+     * {{field.comment}}
+     */
     set {{field.ts_style_name}}(value: {{db_ts_define_type ctype}}) {
         {{~if db_field_cannot_null~}}
         if (value == null) throw new Error()
@@ -105,6 +117,9 @@ export {{x.ts_class_modifier}} class {{name}} extends {{if parent_def_type}} {{x
     }
 
         {{~else~}}
+    /**
+     * {{field.comment}}
+     */
     get {{field.ts_style_name}}(): {{db_ts_define_type ctype}}  { return {{field.internal_name_with_this}} }
         {{~end~}}
     {{~end~}}
@@ -188,7 +203,6 @@ export {{x.ts_class_modifier}} class {{name}} extends {{if parent_def_type}} {{x
 }}
 
 {{x.typescript_namespace_begin}}
-
  class {{internal_table_type}} extends TxnTableGeneric<{{db_ts_define_type key_ttype}},{{db_ts_define_type value_ttype}}> {
     constructor() {
         super({{x.table_uid}}, ""{{x.full_name}}"")
@@ -217,7 +231,9 @@ export {{x.ts_class_modifier}} class {{name}} extends {{if parent_def_type}} {{x
     }
 }
 
-
+/**
+ * {{x.comment}}
+ */
 export class {{name}} {
     static readonly _table = new {{internal_table_type}}();
     static get table(): TxnTableGeneric<{{db_ts_define_type key_ttype}},{{db_ts_define_type value_ttype}}> { return this._table }

src/Luban.Job.Db/Source/RawDefs/Table.cs

@@ -13,5 +13,7 @@ namespace Luban.Job.Db.RawDefs
         public string ValueType { get; set; }
 
         public bool IsPersistent { get; set; }
+
+        public string Comment { get; set; }
     }
 }

src/Luban.Job.Proto/Source/Defs/DefProto.cs

@@ -14,6 +14,7 @@ namespace Luban.Job.Proto.Defs
             Name = b.Name;
             Namespace = b.Namespace;
             Id = b.Id;
+            Comment = b.Comment;
 
             foreach (var field in b.Fields)
             {

src/Luban.Job.Proto/Source/Defs/DefRpc.cs

@@ -16,6 +16,7 @@ namespace Luban.Job.Proto.Defs
             Id = r.Id;
             ArgType = r.ArgType;
             ResType = r.ResType;
+            Comment = r.Comment;
         }
 
         public string ArgType { get; set; }

src/Luban.Job.Proto/Source/Defs/ProtoDefLoader.cs

@@ -47,24 +47,26 @@ namespace Luban.Job.Proto.Defs
                 Namespace = CurNamespace,
                 ArgType = XmlUtil.GetRequiredAttribute(e, "arg"),
                 ResType = XmlUtil.GetRequiredAttribute(e, "res"),
+                Comment = XmlUtil.GetOptionalAttribute(e, "comment"),
             };
             s_logger.Trace("add rpc:{@rpc}", r);
             _rpcs.Add(r);
         }
 
 
-        private readonly List<string> protoAttrs = new List<string> { "id" };
+        private readonly List<string> protoOptionalAttrs = new List<string> { "id", "comment" };
         private readonly List<string> protoRequiredAttrs = new List<string> { "name" };
 
         private void AddProto(XElement e)
         {
-            ValidAttrKeys(e, protoAttrs, protoRequiredAttrs);
+            ValidAttrKeys(e, protoOptionalAttrs, protoRequiredAttrs);
 
             var p = new PProto()
             {
                 Name = XmlUtil.GetRequiredAttribute(e, "name"),
                 Namespace = CurNamespace,
                 Id = XmlUtil.GetOptionIntAttribute(e, "id"),
+                Comment = XmlUtil.GetOptionalAttribute(e, "comment"),
             };
 
             foreach (XElement fe in e.Elements())

src/Luban.Job.Proto/Source/Generate/CsRender.cs

@@ -53,6 +53,9 @@ using Bright.Serialization;
 namespace {{x.namespace_with_top_module}}
 {
 
+    /// <summary>
+    /// {{x.comment}}
+    /// </summary>
     public  {{if is_value_type}}struct{{else}}{{x.cs_class_modifier}} class{{end}} {{name}} : {{if parent_def_type}} {{parent}} {{else}} Bright.Serialization.BeanBase {{end}}
     {
         {{~if !is_value_type~}}
@@ -108,8 +111,13 @@ namespace {{x.namespace_with_top_module}}
         {{~end~}}
             return x;
         }
+
         {{~ for field in fields ~}}
+        /// <summary>
+        /// {{field.comment}}
+        /// </summary>
          public {{cs_define_type field.ctype}} {{field.cs_style_name}};
+
         {{~end~}}
 
         {{~if !is_abstract_type~}}
@@ -164,11 +172,17 @@ using Bright.Serialization;
 
 namespace {{x.namespace_with_top_module}}
 {
-   
+    /// <summary>
+    /// {{x.comment}}
+    /// </summary>
     public sealed class {{name}} : Bright.Net.Codecs.Protocol
     {
         {{~ for field in fields ~}}
+        /// <summary>
+        /// {{field.comment}}
+        /// </summary>
          public {{cs_define_type field.ctype}} {{field.cs_style_name}};
+
         {{~end~}}
 
         public {{name}}()
@@ -250,6 +264,9 @@ using Bright.Serialization;
 namespace {{x.namespace_with_top_module}}
 {
    
+    /// <summary>
+    /// {{x.comment}}
+    /// </summary>
     public sealed class {{name}} : Bright.Net.Codecs.Rpc<{{cs_define_type targ_type}}, {{cs_define_type tres_type}}>
     {
         public {{name}}()
@@ -295,7 +312,6 @@ using Bright.Serialization;
 
 namespace {{namespace}}
 {
-   
     public static class {{name}}
     {
         public static System.Collections.Generic.Dictionary<int, Bright.Net.Codecs.ProtocolCreator> Factories { get; } = new System.Collections.Generic.Dictionary<int, Bright.Net.Codecs.ProtocolCreator>

src/Luban.Job.Proto/Source/Generate/TypescriptRender.cs

@@ -55,6 +55,9 @@ namespace Luban.Job.Proto.Generate
 
 {{x.typescript_namespace_begin}}
 
+/**
+ * {{x.comment}}
+ */
 export {{if x.is_abstract_type}} abstract {{end}} class {{name}} extends {{if parent_def_type}}{{x.parent}}{{else}}BeanBase{{end}} {
 {{~if x.is_abstract_type~}}
     static serializeTo(_buf_ : ByteBuf, _bean_ : {{name}}) {
@@ -86,6 +89,9 @@ export {{if x.is_abstract_type}} abstract {{end}} class {{name}} extends {{if pa
 
 
     {{~ for field in fields ~}}
+    /**
+     * {{field.comment}}
+     */
      {{field.ts_style_name}}{{if field.is_nullable}}?{{end}} : {{ts_define_type field.ctype}}
     {{~end~}}
 
@@ -143,12 +149,18 @@ export {{if x.is_abstract_type}} abstract {{end}} class {{name}} extends {{if pa
 }}
 {{x.typescript_namespace_begin}}
 
+/**
+ * {{x.comment}}
+ */
 export class {{name}} extends Protocol {
     static readonly ID = {{x.id}}
     getTypeId() { return {{name}}.ID }
 
 
     {{~ for field in fields ~}}
+    /**
+     * {{field.comment}}
+     */
      {{field.ts_style_name}}{{if field.is_nullable}}?{{end}} : {{ts_define_type field.ctype}}
     {{~end~}}
 

src/Luban.Job.Proto/Source/RawDefs/PProto.cs

@@ -12,6 +12,8 @@ namespace Luban.Job.Proto.RawDefs
 
         public int Id { get; set; }
 
+        public string Comment { get; set; }
+
         public List<Field> Fields { get; set; } = new List<Field>();
     }
 }

src/Luban.Job.Proto/Source/RawDefs/PRpc.cs

@@ -12,5 +12,7 @@ namespace Luban.Job.Proto.RawDefs
         public string ArgType { get; set; }
 
         public string ResType { get; set; }
+
+        public string Comment { get; set; }
     }
 }