generate source docs from descriptions (#778)

szehetner · web-flow · commit 3a4cc5d0363b · 2020-05-04T16:07:41.000+01:00
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/csharp/CSharpGenerator.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/csharp/CSharpGenerator.java
@@ -94,6 +94,7 @@ public void generate() throws IOException
             try (Writer out = outputManager.createOutput(className))
             {
                 out.append(generateFileHeader(ir.applicableNamespace()));
+                out.append(generateDocumentation(BASE_INDENT, msgToken));
                 out.append(generateClassDeclaration(className));
                 out.append(generateMessageFlyweightCode(className, msgToken, BASE_INDENT));
 
@@ -168,16 +169,18 @@ private void generateGroupClassHeader(
         final int dimensionHeaderLength = tokens.get(index + 1).encodedLength();
 
         sb.append(String.format("\n" +
-            indent + "public sealed partial class %1$sGroup\n" +
+            "%1$s" +
+            indent + "public sealed partial class %2$sGroup\n" +
             indent + "{\n" +
-            indent + INDENT + "private readonly %2$s _dimensions = new %2$s();\n" +
-            indent + INDENT + "private %3$s _parentMessage;\n" +
+            indent + INDENT + "private readonly %3$s _dimensions = new %3$s();\n" +
+            indent + INDENT + "private %4$s _parentMessage;\n" +
             indent + INDENT + "private DirectBuffer _buffer;\n" +
             indent + INDENT + "private int _blockLength;\n" +
             indent + INDENT + "private int _actingVersion;\n" +
             indent + INDENT + "private int _count;\n" +
             indent + INDENT + "private int _index;\n" +
             indent + INDENT + "private int _offset;\n",
+            generateDocumentation(indent, tokens.get(index)),
             formatClassName(groupName),
             dimensionsClassName,
             parentMessageClassName));
@@ -318,14 +321,16 @@ private CharSequence generateGroupProperty(final String groupName, final Token t
         generateSinceActingDeprecated(sb, indent, toUpperFirstChar(groupName), token);
 
         sb.append(String.format("\n" +
-            indent + "public %1$sGroup %2$s\n" +
+            "%1$s" +
+            indent + "public %2$sGroup %3$s\n" +
             indent + "{\n" +
             indent + INDENT + "get\n" +
             indent + INDENT + "{\n" +
-            indent + INDENT + INDENT + "_%3$s.WrapForDecode(_parentMessage, _buffer, _actingVersion);\n" +
-            indent + INDENT + INDENT + "return _%3$s;\n" +
+            indent + INDENT + INDENT + "_%4$s.WrapForDecode(_parentMessage, _buffer, _actingVersion);\n" +
+            indent + INDENT + INDENT + "return _%4$s;\n" +
             indent + INDENT + "}\n" +
             indent + "}\n",
+            generateDocumentation(indent, token),
             className,
             toUpperFirstChar(groupName),
             toLowerFirstChar(groupName)));
@@ -453,6 +458,7 @@ private void generateBitSet(final List<Token> tokens) throws IOException
         try (Writer out = outputManager.createOutput(enumName))
         {
             out.append(generateFileHeader(ir.applicableNamespace()));
+            out.append(generateDocumentation(INDENT, enumToken));
             final String enumPrimitiveType = cSharpTypeName(enumToken.encoding().primitiveType());
             out.append(generateEnumDeclaration(enumName, enumPrimitiveType, true));
 
@@ -471,6 +477,7 @@ private void generateEnum(final List<Token> tokens) throws IOException
         try (Writer out = outputManager.createOutput(enumName))
         {
             out.append(generateFileHeader(ir.applicableNamespace()));
+            out.append(generateDocumentation(INDENT, enumToken));
             final String enumPrimitiveType = cSharpTypeName(enumToken.encoding().primitiveType());
             out.append(generateEnumDeclaration(enumName, enumPrimitiveType, false));
 
@@ -488,6 +495,7 @@ private void generateComposite(final List<Token> tokens) throws IOException
         try (Writer out = outputManager.createOutput(compositeName))
         {
             out.append(generateFileHeader(ir.applicableNamespace()));
+            out.append(generateDocumentation(INDENT, tokens.get(0)));
             out.append(generateClassDeclaration(compositeName));
             out.append(generateFixedFlyweightCode(tokens.get(0).encodedLength()));
             out.append(generateCompositePropertyElements(tokens.subList(1, tokens.size() - 1), BASE_INDENT));
@@ -557,7 +565,8 @@ private CharSequence generateEnumValues(final List<Token> tokens, final Token en
 
         for (final Token token : tokens)
         {
-            sb.append(INDENT).append(INDENT).append(token.name()).append(" = ")
+            sb.append(generateDocumentation(INDENT + INDENT, token))
+              .append(INDENT).append(INDENT).append(token.name()).append(" = ")
               .append(token.encoding().constValue()).append(",\n");
         }
 
@@ -607,6 +616,21 @@ private CharSequence generateClassDeclaration(final String className)
             className);
     }
 
+    public static String generateDocumentation(final String indent, final Token token)
+    {
+        final String description = token.description();
+        if (null == description || description.isEmpty())
+        {
+            return "";
+        }
+
+        return String.format(
+            indent + "/// <summary>\n" +
+            indent + "/// %s\n" +
+            indent + "/// </summary>\n",
+            description);
+    }
+
     private void generateMetaAttributeEnum() throws IOException
     {
         try (Writer out = outputManager.createOutput(META_ATTRIBUTE_ENUM))
@@ -715,18 +739,20 @@ private CharSequence generateSingleValueProperty(
         final String byteOrderStr = generateByteOrder(byteOrder, typeToken.encoding().primitiveType().size());
 
         return String.format("\n" +
-            indent + "public %1$s %2$s\n" +
+            "%1$s" +
+            indent + "public %2$s %3$s\n" +
             indent + "{\n" +
             indent + INDENT + "get\n" +
             indent + INDENT + "{\n" +
-            "%3$s" +
-            indent + INDENT + INDENT + "return _buffer.%4$sGet%6$s(_offset + %5$d);\n" +
+            "%4$s" +
+            indent + INDENT + INDENT + "return _buffer.%5$sGet%7$s(_offset + %6$d);\n" +
             indent + INDENT + "}\n" +
             indent + INDENT + "set\n" +
             indent + INDENT + "{\n" +
-            indent + INDENT + INDENT + "_buffer.%4$sPut%6$s(_offset + %5$d, value);\n" +
+            indent + INDENT + INDENT + "_buffer.%5$sPut%7$s(_offset + %6$d, value);\n" +
             indent + INDENT + "}\n" +
             indent + "}\n\n",
+            generateDocumentation(indent, fieldToken),
             typeName,
             toUpperFirstChar(propertyName),
             generateFieldNotPresentCondition(fieldToken.version(), typeToken.encoding(), indent),
@@ -825,28 +851,32 @@ private CharSequence generateArrayProperty(
             propName, fieldLength));
 
         sb.append(String.format("\n" +
-            indent + "public %1$s Get%2$s(int index)\n" +
+            "%1$s" +
+            indent + "public %2$s Get%3$s(int index)\n" +
             indent + "{\n" +
-            indent + INDENT + "if ((uint) index >= %3$d)\n" +
+            indent + INDENT + "if ((uint) index >= %4$d)\n" +
             indent + INDENT + "{\n" +
             indent + INDENT + INDENT + "ThrowHelper.ThrowIndexOutOfRangeException(index);\n" +
             indent + INDENT + "}\n\n" +
-            "%4$s" +
-            indent + INDENT + "return _buffer.%5$sGet%8$s(_offset + %6$d + (index * %7$d));\n" +
+            "%5$s" +
+            indent + INDENT + "return _buffer.%6$sGet%9$s(_offset + %7$d + (index * %8$d));\n" +
             indent + "}\n",
+            generateDocumentation(indent, fieldToken),
             typeName, propName, fieldLength,
             generateFieldNotPresentCondition(fieldToken.version(), typeToken.encoding(), indent),
             typePrefix, offset, typeSize, byteOrderStr));
 
         sb.append(String.format("\n" +
-            indent + "public void Set%1$s(int index, %2$s value)\n" +
+            "%1$s" +
+            indent + "public void Set%2$s(int index, %3$s value)\n" +
             indent + "{\n" +
-            indent + INDENT + "if ((uint) index >= %3$d)\n" +
+            indent + INDENT + "if ((uint) index >= %4$d)\n" +
             indent + INDENT + "{\n" +
             indent + INDENT + INDENT + "ThrowHelper.ThrowIndexOutOfRangeException(index);\n" +
             indent + INDENT + "}\n\n" +
-            indent + INDENT + "_buffer.%4$sPut%7$s(_offset + %5$d + (index * %6$d), value);\n" +
+            indent + INDENT + "_buffer.%5$sPut%8$s(_offset + %6$d + (index * %7$d), value);\n" +
             indent + "}\n",
+            generateDocumentation(indent, fieldToken),
             propName, typeName, fieldLength, typePrefix, offset, typeSize, byteOrderStr));
 
         if (typeToken.encoding().primitiveType() == PrimitiveType.CHAR)
@@ -921,7 +951,9 @@ private CharSequence generateConstPropertyMethods(
             // ODE: we generate a property here because the constant could
             // become a field in a newer version of the protocol
             return String.format("\n" +
-                indent + INDENT + "public %1$s %2$s { get { return %3$s; } }\n",
+                "%1s" +
+                indent + INDENT + "public %2$s %3$s { get { return %4$s; } }\n",
+                generateDocumentation(indent + INDENT, token),
                 cSharpTypeName(token.encoding().primitiveType()),
                 toUpperFirstChar(propertyName),
                 generateLiteral(token.encoding().primitiveType(), token.encoding().constValue().toString()));
@@ -1201,32 +1233,36 @@ private CharSequence generateEnumProperty(
             final String constValue = fieldToken.encoding().constValue().toString();
 
             return String.format("\n" +
-                indent + INDENT + "public %1$s %2$s\n" +
+                "%1$s" +
+                indent + INDENT + "public %2$s %3$s\n" +
                 indent + INDENT + "{\n" +
                 indent + INDENT + INDENT + "get\n" +
                 indent + INDENT + INDENT + "{\n" +
-                indent + INDENT + INDENT + INDENT + "return %3$s;\n" +
+                indent + INDENT + INDENT + INDENT + "return %4$s;\n" +
                 indent + INDENT + INDENT + "}\n" +
                 indent + INDENT + "}\n\n",
+                generateDocumentation(indent + INDENT, fieldToken),
                 enumName,
                 toUpperFirstChar(propertyName),
                 constValue);
         }
         else
         {
             return String.format("\n" +
-                indent + INDENT + "public %1$s %2$s\n" +
+                "%1$s" +
+                indent + INDENT + "public %2$s %3$s\n" +
                 indent + INDENT + "{\n" +
                 indent + INDENT + INDENT + "get\n" +
                 indent + INDENT + INDENT + "{\n" +
-                "%3$s" +
-                indent + INDENT + INDENT + INDENT + "return (%4$s)_buffer.%5$sGet%7$s(_offset + %6$d);\n" +
+                "%4$s" +
+                indent + INDENT + INDENT + INDENT + "return (%5$s)_buffer.%6$sGet%8$s(_offset + %7$d);\n" +
                 indent + INDENT + INDENT + "}\n" +
                 indent + INDENT + INDENT + "set\n" +
                 indent + INDENT + INDENT + "{\n" +
-                indent + INDENT + INDENT + INDENT + "_buffer.%5$sPut%7$s(_offset + %6$d, (%8$s)value);\n" +
+                indent + INDENT + INDENT + INDENT + "_buffer.%6$sPut%8$s(_offset + %7$d, (%9$s)value);\n" +
                 indent + INDENT + INDENT + "}\n" +
                 indent + INDENT + "}\n\n",
+                generateDocumentation(indent + INDENT, fieldToken),
                 enumName,
                 toUpperFirstChar(propertyName),
                 generateEnumFieldNotPresentCondition(fieldToken.version(), enumName, indent),
@@ -1249,18 +1285,20 @@ private String generateBitSetProperty(
         final String typeName = cSharpTypeName(typeToken.encoding().primitiveType());
 
         return String.format("\n" +
-            indent + INDENT + "public %1$s %2$s\n" +
+            "%1$s" +
+            indent + INDENT + "public %2$s %3$s\n" +
             indent + INDENT + "{\n" +
             indent + INDENT + INDENT + "get\n" +
             indent + INDENT + INDENT + "{\n" +
-            "%3$s" +
-            indent + INDENT + INDENT + INDENT + "return (%4$s)_buffer.%5$sGet%7$s(_offset + %6$d);\n" +
+            "%4$s" +
+            indent + INDENT + INDENT + INDENT + "return (%5$s)_buffer.%6$sGet%8$s(_offset + %7$d);\n" +
             indent + INDENT + INDENT + "}\n" +
             indent + INDENT + INDENT + "set\n" +
             indent + INDENT + INDENT + "{\n" +
-            indent + INDENT + INDENT + INDENT + "_buffer.%5$sPut%7$s(_offset + %6$d, (%8$s)value);\n" +
+            indent + INDENT + INDENT + INDENT + "_buffer.%6$sPut%8$s(_offset + %7$d, (%9$s)value);\n" +
             indent + INDENT + INDENT + "}\n" +
             indent + INDENT + "}\n",
+            generateDocumentation(indent + INDENT, fieldToken),
             bitSetName,
             toUpperFirstChar(propertyName),
             generateBitSetNotPresentCondition(fieldToken.version(), indent, bitSetName),
@@ -1285,15 +1323,17 @@ private Object generateCompositeProperty(
             compositeName));
 
         sb.append(String.format("\n" +
-            indent + INDENT + "public %1$s %2$s\n" +
+            "%1$s" +
+            indent + INDENT + "public %2$s %3$s\n" +
             indent + INDENT + "{\n" +
             indent + INDENT + INDENT + "get\n" +
             indent + INDENT + INDENT + "{\n" +
-            "%3$s" +
-            indent + INDENT + INDENT + INDENT + "_%4$s.Wrap(_buffer, _offset + %5$d, _actingVersion);\n" +
-            indent + INDENT + INDENT + INDENT + "return _%4$s;\n" +
+            "%4$s" +
+            indent + INDENT + INDENT + INDENT + "_%5$s.Wrap(_buffer, _offset + %6$d, _actingVersion);\n" +
+            indent + INDENT + INDENT + INDENT + "return _%5$s;\n" +
             indent + INDENT + INDENT + "}\n" +
             indent + INDENT + "}\n",
+            generateDocumentation(indent + INDENT, fieldToken),
             compositeName,
             toUpperFirstChar(propertyName),
             generateTypeFieldNotPresentCondition(fieldToken.version(), indent),
