Skip to content

Commit 3a4cc5d

Browse files
szehetnerszehetner
authored
generate source docs from descriptions (aeron-io#778)
1 parent f9170b0 commit 3a4cc5d

File tree

1 file changed

+73
-33
lines changed

1 file changed

+73
-33
lines changed

‎sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/csharp/CSharpGenerator.java‎

Lines changed: 73 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,7 @@ public void generate() throws IOException
9494
try (Writer out = outputManager.createOutput(className))
9595
{
9696
out.append(generateFileHeader(ir.applicableNamespace()));
97+
out.append(generateDocumentation(BASE_INDENT, msgToken));
9798
out.append(generateClassDeclaration(className));
9899
out.append(generateMessageFlyweightCode(className, msgToken, BASE_INDENT));
99100

@@ -168,16 +169,18 @@ private void generateGroupClassHeader(
168169
final int dimensionHeaderLength = tokens.get(index + 1).encodedLength();
169170

170171
sb.append(String.format("\n" +
171-
indent + "public sealed partial class %1$sGroup\n" +
172+
"%1$s" +
173+
indent + "public sealed partial class %2$sGroup\n" +
172174
indent + "{\n" +
173-
indent + INDENT + "private readonly %2$s _dimensions = new %2$s();\n" +
174-
indent + INDENT + "private %3$s _parentMessage;\n" +
175+
indent + INDENT + "private readonly %3$s _dimensions = new %3$s();\n" +
176+
indent + INDENT + "private %4$s _parentMessage;\n" +
175177
indent + INDENT + "private DirectBuffer _buffer;\n" +
176178
indent + INDENT + "private int _blockLength;\n" +
177179
indent + INDENT + "private int _actingVersion;\n" +
178180
indent + INDENT + "private int _count;\n" +
179181
indent + INDENT + "private int _index;\n" +
180182
indent + INDENT + "private int _offset;\n",
183+
generateDocumentation(indent, tokens.get(index)),
181184
formatClassName(groupName),
182185
dimensionsClassName,
183186
parentMessageClassName));
@@ -318,14 +321,16 @@ private CharSequence generateGroupProperty(final String groupName, final Token t
318321
generateSinceActingDeprecated(sb, indent, toUpperFirstChar(groupName), token);
319322

320323
sb.append(String.format("\n" +
321-
indent + "public %1$sGroup %2$s\n" +
324+
"%1$s" +
325+
indent + "public %2$sGroup %3$s\n" +
322326
indent + "{\n" +
323327
indent + INDENT + "get\n" +
324328
indent + INDENT + "{\n" +
325-
indent + INDENT + INDENT + "_%3$s.WrapForDecode(_parentMessage, _buffer, _actingVersion);\n" +
326-
indent + INDENT + INDENT + "return _%3$s;\n" +
329+
indent + INDENT + INDENT + "_%4$s.WrapForDecode(_parentMessage, _buffer, _actingVersion);\n" +
330+
indent + INDENT + INDENT + "return _%4$s;\n" +
327331
indent + INDENT + "}\n" +
328332
indent + "}\n",
333+
generateDocumentation(indent, token),
329334
className,
330335
toUpperFirstChar(groupName),
331336
toLowerFirstChar(groupName)));
@@ -453,6 +458,7 @@ private void generateBitSet(final List<Token> tokens) throws IOException
453458
try (Writer out = outputManager.createOutput(enumName))
454459
{
455460
out.append(generateFileHeader(ir.applicableNamespace()));
461+
out.append(generateDocumentation(INDENT, enumToken));
456462
final String enumPrimitiveType = cSharpTypeName(enumToken.encoding().primitiveType());
457463
out.append(generateEnumDeclaration(enumName, enumPrimitiveType, true));
458464

@@ -471,6 +477,7 @@ private void generateEnum(final List<Token> tokens) throws IOException
471477
try (Writer out = outputManager.createOutput(enumName))
472478
{
473479
out.append(generateFileHeader(ir.applicableNamespace()));
480+
out.append(generateDocumentation(INDENT, enumToken));
474481
final String enumPrimitiveType = cSharpTypeName(enumToken.encoding().primitiveType());
475482
out.append(generateEnumDeclaration(enumName, enumPrimitiveType, false));
476483

@@ -488,6 +495,7 @@ private void generateComposite(final List<Token> tokens) throws IOException
488495
try (Writer out = outputManager.createOutput(compositeName))
489496
{
490497
out.append(generateFileHeader(ir.applicableNamespace()));
498+
out.append(generateDocumentation(INDENT, tokens.get(0)));
491499
out.append(generateClassDeclaration(compositeName));
492500
out.append(generateFixedFlyweightCode(tokens.get(0).encodedLength()));
493501
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
557565

558566
for (final Token token : tokens)
559567
{
560-
sb.append(INDENT).append(INDENT).append(token.name()).append(" = ")
568+
sb.append(generateDocumentation(INDENT + INDENT, token))
569+
.append(INDENT).append(INDENT).append(token.name()).append(" = ")
561570
.append(token.encoding().constValue()).append(",\n");
562571
}
563572

@@ -607,6 +616,21 @@ private CharSequence generateClassDeclaration(final String className)
607616
className);
608617
}
609618

619+
public static String generateDocumentation(final String indent, final Token token)
620+
{
621+
final String description = token.description();
622+
if (null == description || description.isEmpty())
623+
{
624+
return "";
625+
}
626+
627+
return String.format(
628+
indent + "/// <summary>\n" +
629+
indent + "/// %s\n" +
630+
indent + "/// </summary>\n",
631+
description);
632+
}
633+
610634
private void generateMetaAttributeEnum() throws IOException
611635
{
612636
try (Writer out = outputManager.createOutput(META_ATTRIBUTE_ENUM))
@@ -715,18 +739,20 @@ private CharSequence generateSingleValueProperty(
715739
final String byteOrderStr = generateByteOrder(byteOrder, typeToken.encoding().primitiveType().size());
716740

717741
return String.format("\n" +
718-
indent + "public %1$s %2$s\n" +
742+
"%1$s" +
743+
indent + "public %2$s %3$s\n" +
719744
indent + "{\n" +
720745
indent + INDENT + "get\n" +
721746
indent + INDENT + "{\n" +
722-
"%3$s" +
723-
indent + INDENT + INDENT + "return _buffer.%4$sGet%6$s(_offset + %5$d);\n" +
747+
"%4$s" +
748+
indent + INDENT + INDENT + "return _buffer.%5$sGet%7$s(_offset + %6$d);\n" +
724749
indent + INDENT + "}\n" +
725750
indent + INDENT + "set\n" +
726751
indent + INDENT + "{\n" +
727-
indent + INDENT + INDENT + "_buffer.%4$sPut%6$s(_offset + %5$d, value);\n" +
752+
indent + INDENT + INDENT + "_buffer.%5$sPut%7$s(_offset + %6$d, value);\n" +
728753
indent + INDENT + "}\n" +
729754
indent + "}\n\n",
755+
generateDocumentation(indent, fieldToken),
730756
typeName,
731757
toUpperFirstChar(propertyName),
732758
generateFieldNotPresentCondition(fieldToken.version(), typeToken.encoding(), indent),
@@ -825,28 +851,32 @@ private CharSequence generateArrayProperty(
825851
propName, fieldLength));
826852

827853
sb.append(String.format("\n" +
828-
indent + "public %1$s Get%2$s(int index)\n" +
854+
"%1$s" +
855+
indent + "public %2$s Get%3$s(int index)\n" +
829856
indent + "{\n" +
830-
indent + INDENT + "if ((uint) index >= %3$d)\n" +
857+
indent + INDENT + "if ((uint) index >= %4$d)\n" +
831858
indent + INDENT + "{\n" +
832859
indent + INDENT + INDENT + "ThrowHelper.ThrowIndexOutOfRangeException(index);\n" +
833860
indent + INDENT + "}\n\n" +
834-
"%4$s" +
835-
indent + INDENT + "return _buffer.%5$sGet%8$s(_offset + %6$d + (index * %7$d));\n" +
861+
"%5$s" +
862+
indent + INDENT + "return _buffer.%6$sGet%9$s(_offset + %7$d + (index * %8$d));\n" +
836863
indent + "}\n",
864+
generateDocumentation(indent, fieldToken),
837865
typeName, propName, fieldLength,
838866
generateFieldNotPresentCondition(fieldToken.version(), typeToken.encoding(), indent),
839867
typePrefix, offset, typeSize, byteOrderStr));
840868

841869
sb.append(String.format("\n" +
842-
indent + "public void Set%1$s(int index, %2$s value)\n" +
870+
"%1$s" +
871+
indent + "public void Set%2$s(int index, %3$s value)\n" +
843872
indent + "{\n" +
844-
indent + INDENT + "if ((uint) index >= %3$d)\n" +
873+
indent + INDENT + "if ((uint) index >= %4$d)\n" +
845874
indent + INDENT + "{\n" +
846875
indent + INDENT + INDENT + "ThrowHelper.ThrowIndexOutOfRangeException(index);\n" +
847876
indent + INDENT + "}\n\n" +
848-
indent + INDENT + "_buffer.%4$sPut%7$s(_offset + %5$d + (index * %6$d), value);\n" +
877+
indent + INDENT + "_buffer.%5$sPut%8$s(_offset + %6$d + (index * %7$d), value);\n" +
849878
indent + "}\n",
879+
generateDocumentation(indent, fieldToken),
850880
propName, typeName, fieldLength, typePrefix, offset, typeSize, byteOrderStr));
851881

852882
if (typeToken.encoding().primitiveType() == PrimitiveType.CHAR)
@@ -921,7 +951,9 @@ private CharSequence generateConstPropertyMethods(
921951
// ODE: we generate a property here because the constant could
922952
// become a field in a newer version of the protocol
923953
return String.format("\n" +
924-
indent + INDENT + "public %1$s %2$s { get { return %3$s; } }\n",
954+
"%1s" +
955+
indent + INDENT + "public %2$s %3$s { get { return %4$s; } }\n",
956+
generateDocumentation(indent + INDENT, token),
925957
cSharpTypeName(token.encoding().primitiveType()),
926958
toUpperFirstChar(propertyName),
927959
generateLiteral(token.encoding().primitiveType(), token.encoding().constValue().toString()));
@@ -1201,32 +1233,36 @@ private CharSequence generateEnumProperty(
12011233
final String constValue = fieldToken.encoding().constValue().toString();
12021234

12031235
return String.format("\n" +
1204-
indent + INDENT + "public %1$s %2$s\n" +
1236+
"%1$s" +
1237+
indent + INDENT + "public %2$s %3$s\n" +
12051238
indent + INDENT + "{\n" +
12061239
indent + INDENT + INDENT + "get\n" +
12071240
indent + INDENT + INDENT + "{\n" +
1208-
indent + INDENT + INDENT + INDENT + "return %3$s;\n" +
1241+
indent + INDENT + INDENT + INDENT + "return %4$s;\n" +
12091242
indent + INDENT + INDENT + "}\n" +
12101243
indent + INDENT + "}\n\n",
1244+
generateDocumentation(indent + INDENT, fieldToken),
12111245
enumName,
12121246
toUpperFirstChar(propertyName),
12131247
constValue);
12141248
}
12151249
else
12161250
{
12171251
return String.format("\n" +
1218-
indent + INDENT + "public %1$s %2$s\n" +
1252+
"%1$s" +
1253+
indent + INDENT + "public %2$s %3$s\n" +
12191254
indent + INDENT + "{\n" +
12201255
indent + INDENT + INDENT + "get\n" +
12211256
indent + INDENT + INDENT + "{\n" +
1222-
"%3$s" +
1223-
indent + INDENT + INDENT + INDENT + "return (%4$s)_buffer.%5$sGet%7$s(_offset + %6$d);\n" +
1257+
"%4$s" +
1258+
indent + INDENT + INDENT + INDENT + "return (%5$s)_buffer.%6$sGet%8$s(_offset + %7$d);\n" +
12241259
indent + INDENT + INDENT + "}\n" +
12251260
indent + INDENT + INDENT + "set\n" +
12261261
indent + INDENT + INDENT + "{\n" +
1227-
indent + INDENT + INDENT + INDENT + "_buffer.%5$sPut%7$s(_offset + %6$d, (%8$s)value);\n" +
1262+
indent + INDENT + INDENT + INDENT + "_buffer.%6$sPut%8$s(_offset + %7$d, (%9$s)value);\n" +
12281263
indent + INDENT + INDENT + "}\n" +
12291264
indent + INDENT + "}\n\n",
1265+
generateDocumentation(indent + INDENT, fieldToken),
12301266
enumName,
12311267
toUpperFirstChar(propertyName),
12321268
generateEnumFieldNotPresentCondition(fieldToken.version(), enumName, indent),
@@ -1249,18 +1285,20 @@ private String generateBitSetProperty(
12491285
final String typeName = cSharpTypeName(typeToken.encoding().primitiveType());
12501286

12511287
return String.format("\n" +
1252-
indent + INDENT + "public %1$s %2$s\n" +
1288+
"%1$s" +
1289+
indent + INDENT + "public %2$s %3$s\n" +
12531290
indent + INDENT + "{\n" +
12541291
indent + INDENT + INDENT + "get\n" +
12551292
indent + INDENT + INDENT + "{\n" +
1256-
"%3$s" +
1257-
indent + INDENT + INDENT + INDENT + "return (%4$s)_buffer.%5$sGet%7$s(_offset + %6$d);\n" +
1293+
"%4$s" +
1294+
indent + INDENT + INDENT + INDENT + "return (%5$s)_buffer.%6$sGet%8$s(_offset + %7$d);\n" +
12581295
indent + INDENT + INDENT + "}\n" +
12591296
indent + INDENT + INDENT + "set\n" +
12601297
indent + INDENT + INDENT + "{\n" +
1261-
indent + INDENT + INDENT + INDENT + "_buffer.%5$sPut%7$s(_offset + %6$d, (%8$s)value);\n" +
1298+
indent + INDENT + INDENT + INDENT + "_buffer.%6$sPut%8$s(_offset + %7$d, (%9$s)value);\n" +
12621299
indent + INDENT + INDENT + "}\n" +
12631300
indent + INDENT + "}\n",
1301+
generateDocumentation(indent + INDENT, fieldToken),
12641302
bitSetName,
12651303
toUpperFirstChar(propertyName),
12661304
generateBitSetNotPresentCondition(fieldToken.version(), indent, bitSetName),
@@ -1285,15 +1323,17 @@ private Object generateCompositeProperty(
12851323
compositeName));
12861324

12871325
sb.append(String.format("\n" +
1288-
indent + INDENT + "public %1$s %2$s\n" +
1326+
"%1$s" +
1327+
indent + INDENT + "public %2$s %3$s\n" +
12891328
indent + INDENT + "{\n" +
12901329
indent + INDENT + INDENT + "get\n" +
12911330
indent + INDENT + INDENT + "{\n" +
1292-
"%3$s" +
1293-
indent + INDENT + INDENT + INDENT + "_%4$s.Wrap(_buffer, _offset + %5$d, _actingVersion);\n" +
1294-
indent + INDENT + INDENT + INDENT + "return _%4$s;\n" +
1331+
"%4$s" +
1332+
indent + INDENT + INDENT + INDENT + "_%5$s.Wrap(_buffer, _offset + %6$d, _actingVersion);\n" +
1333+
indent + INDENT + INDENT + INDENT + "return _%5$s;\n" +
12951334
indent + INDENT + INDENT + "}\n" +
12961335
indent + INDENT + "}\n",
1336+
generateDocumentation(indent + INDENT, fieldToken),
12971337
compositeName,
12981338
toUpperFirstChar(propertyName),
12991339
generateTypeFieldNotPresentCondition(fieldToken.version(), indent),

0 commit comments

Comments
 (0)