[Java] Generate javadoc for bitset options as part of Issues #22 and #289.

Author: mjpt777

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

@@ -1178,14 +1178,16 @@ private CharSequence generateChoiceDecoders(final List<Token> tokens)
 
                 return String.format(
                     "\n" +
-                    "    public boolean %1$s()\n" +
+                    "%1$s" +
+                    "    public boolean %2$s()\n" +
                     "    {\n" +
-                    "        return %2$s;\n" +
+                    "        return %3$s;\n" +
                     "    }\n\n" +
-                    "    public static boolean %1$s(final %3$s value)\n" +
+                    "    public static boolean %2$s(final %4$s value)\n" +
                     "    {\n" +
-                    "        return %4$s;\n" +
+                    "        return %5$s;\n" +
                     "    }\n",
+                    generateOptionDecodeJavadoc(INDENT, token),
                     choiceName,
                     generateChoiceGet(primitiveType, choiceBitIndex, byteOrderStr),
                     argType,
@@ -1209,15 +1211,17 @@ private CharSequence generateChoiceEncoders(final String bitSetClassName, final
 
                 return String.format(
                     "\n" +
-                    "    public %1$s %2$s(final boolean value)\n" +
+                    "%1$s" +
+                    "    public %2$s %3$s(final boolean value)\n" +
                     "    {\n" +
-                    "%3$s\n" +
+                    "%4$s\n" +
                     "        return this;\n" +
                     "    }\n\n" +
-                    "    public static %4$s %2$s(final %4$s bits, final boolean value)\n" +
+                    "    public static %5$s %3$s(final %5$s bits, final boolean value)\n" +
                     "    {\n" +
-                    "%5$s" +
+                    "%6$s" +
                     "    }\n",
+                    generateOptionEncodeJavadoc(INDENT, token),
                     bitSetClassName,
                     choiceName,
                     generateChoicePut(encoding.primitiveType(), choiceBitIndex, byteOrderStr),

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

@@ -59,14 +59,13 @@ public enum Separators
         /**
          * Add separator to a generated StringBuilder
          *
-         * @param builder          the code generation builder to which information should be added
-         * @param indent           the current generated code indentation
-         * @param generatedBuilder the name of the generated StringBuilder to which separator should be added
+         * @param builder     the code generation builder to which information should be added
+         * @param indent      the current generated code indentation
+         * @param builderName of the generated StringBuilder to which separator should be added
          */
-        public void appendToGeneratedBuilder(
-            final StringBuilder builder, final String indent, final String generatedBuilder)
+        public void appendToGeneratedBuilder(final StringBuilder builder, final String indent, final String builderName)
         {
-            append(builder, indent, generatedBuilder + ".append('" + symbol + "');");
+            append(builder, indent, builderName + ".append('" + symbol + "');");
         }
 
         public String toString()
@@ -271,4 +270,50 @@ public static String generateTypeJavadoc(final String indent, final Token typeTo
             indent + " * " + description + '\n' +
             indent + " */\n";
     }
+
+    /**
+     * Generate the Javadoc comment header for a bitset choice option decode method.
+     *
+     * @param indent      level for the comment.
+     * @param optionToken for the type.
+     * @return a string representation of the Javadoc comment.
+     */
+    public static String generateOptionDecodeJavadoc(final String indent, final Token optionToken)
+    {
+        final String description = optionToken.description();
+        if (null == description || description.length() == 0)
+        {
+            return "";
+        }
+
+        return
+            indent + "/**\n" +
+            indent + " * " + description + '\n' +
+            indent + " *\n" +
+            indent + " * @return true if " + optionToken.name() + " is set or false if not\n" +
+            indent + " */\n";
+    }
+
+    /**
+     * Generate the Javadoc comment header for a bitset choice option encode method.
+     *
+     * @param indent      level for the comment.
+     * @param optionToken for the type.
+     * @return a string representation of the Javadoc comment.
+     */
+    public static String generateOptionEncodeJavadoc(final String indent, final Token optionToken)
+    {
+        final String description = optionToken.description();
+        if (null == description || description.length() == 0)
+        {
+            return "";
+        }
+
+        return
+            indent + "/**\n" +
+            indent + " * " + description + '\n' +
+            indent + " *\n" +
+            indent + " * @param value true if " + optionToken.name() + " is set or false if not\n" +
+            indent + " */\n";
+    }
 }