Skip to content

[C#] Generate source documentation from descriptions #778

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 4, 2020
Merged

[C#] Generate source documentation from descriptions #778

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 73 additions & 33 deletions sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/csharp/CSharpGenerator.java
View file
Open in desktop
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 @@ -1185,32 +1217,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 @@ -1233,18 +1269,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 @@ -1269,15 +1307,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