Skip to content

Commit

Permalink
generate source docs from descriptions (#778)
Browse files Browse the repository at this point in the history
  • Loading branch information
@szehetner
szehetner authored May 4, 2020
1 parent f9170b0 commit 3a4cc5d
Showing 1 changed file with 73 additions and 33 deletions.
106 changes: 73 additions & 33 deletions sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/csharp/CSharpGenerator.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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));

Expand Down Expand Up @@ -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));
Expand Down Expand Up @@ -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)));
Expand Down Expand Up @@ -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));

Expand All @@ -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));

Expand All @@ -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));
Expand Down Expand Up @@ -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");
}

Expand Down Expand Up @@ -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))
Expand Down Expand Up @@ -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),
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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()));
Expand Down Expand Up @@ -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),
Expand All @@ -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),
Expand All @@ -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),
Expand Down

0 comments on commit 3a4cc5d

Please sign in to comment.