[Java] Generate javadoc for enum values as part of Issues aeron-io#22 and aeron-io#289.

Author: mjpt777

sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/java/JavaGenerator.java

@@ -514,7 +514,7 @@ private void generateGroupDecoderClassDeclaration(
  indent + " private int index;\n" +
  indent + " private int offset;\n" +
  indent + " private int blockLength;\n\n",
- generateClassJavadoc(indent, groupToken),
+ generateTypeJavadoc(indent, groupToken),
  formatClassName(groupName),
  dimensionHeaderSize,
  decoderName(dimensionsClassName),
@@ -543,7 +543,7 @@ private void generateGroupEncoderClassDeclaration(
  indent + " private int count;\n" +
  indent + " private int index;\n" +
  indent + " private int offset;\n\n",
- generateClassJavadoc(indent, groupToken),
+ generateTypeJavadoc(indent, groupToken),
  formatClassName(encoderName(groupName)),
  dimensionHeaderSize,
  dimensionsClassName,
@@ -1255,7 +1255,8 @@ private CharSequence generateEnumValues(final List<Token> tokens)
  {
  final Encoding encoding = token.encoding();
  final CharSequence constVal = generateLiteral(encoding.primitiveType(), encoding.constValue().toString());
- sb.append(INDENT).append(token.name()).append('(').append(constVal).append("),\n");
+ sb.append(generateTypeJavadoc(INDENT, token));
+ sb.append(INDENT).append(token.name()).append('(').append(constVal).append("),\n\n");
  }
 
  final Token token = tokens.get(0);
@@ -1265,9 +1266,15 @@ private CharSequence generateEnumValues(final List<Token> tokens)
 
  if (shouldDecodeUnknownEnumValues)
  {
- sb.append(INDENT).append("SBE_UNKNOWN").append('(').append(nullVal).append("),\n");
+ sb.append(INDENT).append("/**\n");
+ sb.append(INDENT).append(" * To be used to represent a not known value from a later version.\n");
+ sb.append(INDENT).append(" */\n");
+ sb.append(INDENT).append("SBE_UNKNOWN").append('(').append(nullVal).append("),\n\n");
  }
 
+ sb.append(INDENT).append("/**\n");
+ sb.append(INDENT).append(" * To be used to represent not present or null.\n");
+ sb.append(INDENT).append(" */\n");
  sb.append(INDENT).append("NULL_VAL").append('(').append(nullVal).append(");\n\n");
 
  return sb;
@@ -1445,7 +1452,7 @@ private static CharSequence generateDeclaration(
  "@SuppressWarnings(\"all\")\n" +
  "public class %s%s\n" +
  "{\n",
- generateClassJavadoc(BASE_INDENT, typeToken),
+ generateTypeJavadoc(BASE_INDENT, typeToken),
  className,
  implementsString);
  }
@@ -1472,7 +1479,7 @@ private void generateMetaAttributeEnum() throws IOException
  private static CharSequence generateEnumDeclaration(final String name, final Token typeToken)
  {
  return
- generateClassJavadoc(BASE_INDENT, typeToken) +
+ generateTypeJavadoc(BASE_INDENT, typeToken) +
  "@javax.annotation.Generated(value = { \"uk.co.real_logic.sbe.generation.java.JavaGenerator\" })\n" +
  "public enum " + name + "\n{\n";
  }

sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/java/JavaUtil.java

@@ -252,26 +252,23 @@ public static String generateLiteral(final PrimitiveType type, final String valu
  }
 
  /**
- * Generate the Javadoc comment header for a class.
+ * Generate the Javadoc comment header for a type.
  *
- * @param indent  level for the comment.
- * @param classToken for the type.
+ * @param indent level for the comment.
+ * @param typeToken for the type.
  * @return a string representation of the Javadoc comment.
  */
- public static String generateClassJavadoc(final String indent, final Token classToken)
+ public static String generateTypeJavadoc(final String indent, final Token typeToken)
  {
- final String description = classToken.description();
+ final String description = typeToken.description();
  if (null == description || description.length() == 0)
  {
  return "";
  }
 
- final StringBuilder sb = new StringBuilder();
-
- sb.append(indent).append("/**\n");
- sb.append(indent).append(" * ").append(description).append('\n');
- sb.append(indent).append(" */\n");
-
- return sb.toString();
+ return
+ indent + "/**\n" +
+ indent + " * " + description + '\n' +
+ indent + " */\n";
  }
 }