[Java] Tidy up common methods and add javadoc.

mjpt777 · mjpt777 · commit 6ef0c48365df · 2020-05-22T14:36:33.000+01:00
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/codec/java/MethodSelector.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/codec/java/MethodSelector.java
@@ -27,6 +27,9 @@
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * Selects sorted methods of a class that are annotated with {@link GroupOrder}.
+ */
 public class MethodSelector
 {
     private final Set<String> ignoredMethods;
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/Generators.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/Generators.java
@@ -21,6 +21,9 @@
 import java.util.List;
 import java.util.function.BiConsumer;
 
+/**
+ * Common operations available to all {@link CodeGenerator}s.
+ */
 public class Generators
 {
     /**
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/NamedToken.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/NamedToken.java
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/TargetCodeGeneratorLoader.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/TargetCodeGeneratorLoader.java
@@ -27,8 +27,15 @@
 
 import static uk.co.real_logic.sbe.SbeTool.*;
 
+/**
+ * Loader for {@link CodeGenerator}s which target a language. This provide convenient short names rather than the
+ * fully qualified class name of the generator.
+ */
 public enum TargetCodeGeneratorLoader implements TargetCodeGenerator
 {
+    /**
+     * Generates codecs for the Java 8 programming language.
+     */
     JAVA()
     {
         public CodeGenerator newInstance(final Ir ir, final String outputDir)
@@ -44,6 +51,9 @@ public CodeGenerator newInstance(final Ir ir, final String outputDir)
         }
     },
 
+    /**
+     * Generates codecs for the C11 programming language.
+     */
     C()
     {
         public CodeGenerator newInstance(final Ir ir, final String outputDir)
@@ -52,6 +62,9 @@ public CodeGenerator newInstance(final Ir ir, final String outputDir)
         }
     },
 
+    /**
+     * Generates codecs for the C++11 programming language with some conditional includes for C++14 and C++17.
+     */
     CPP()
     {
         public CodeGenerator newInstance(final Ir ir, final String outputDir)
@@ -60,6 +73,9 @@ public CodeGenerator newInstance(final Ir ir, final String outputDir)
         }
     },
 
+    /**
+     * Generates codecs for the Go programming language.
+     */
     GOLANG()
     {
         public CodeGenerator newInstance(final Ir ir, final String outputDir)
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/c/CGenerator.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/c/CGenerator.java
@@ -31,9 +31,14 @@
 import java.util.ArrayList;
 import java.util.List;
 
+import static uk.co.real_logic.sbe.generation.Generators.toLowerFirstChar;
+import static uk.co.real_logic.sbe.generation.Generators.toUpperFirstChar;
 import static uk.co.real_logic.sbe.generation.c.CUtil.*;
 import static uk.co.real_logic.sbe.ir.GenerationUtil.*;
 
+/**
+ * Codec generator for the C11 programming language.
+ */
 @SuppressWarnings("MethodLength")
 public class CGenerator implements CodeGenerator
 {
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/c/CUtil.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/c/CUtil.java
@@ -23,6 +23,8 @@
 import java.util.EnumMap;
 import java.util.Map;
 
+import static uk.co.real_logic.sbe.generation.Generators.toLowerFirstChar;
+
 /**
  * Utilities for mapping between IR and the C language.
  */
@@ -56,28 +58,6 @@ public static String cTypeName(final PrimitiveType primitiveType)
         return PRIMITIVE_TYPE_STRING_ENUM_MAP.get(primitiveType);
     }
 
-    /**
-     * Uppercase the first character of a given String.
-     *
-     * @param str to have the first character upper cased.
-     * @return a new String with the first character in uppercase.
-     */
-    public static String toUpperFirstChar(final String str)
-    {
-        return Character.toUpperCase(str.charAt(0)) + str.substring(1);
-    }
-
-    /**
-     * Lowercase the first character of a given String.
-     *
-     * @param str to have the first character upper cased.
-     * @return a new String with the first character in uppercase.
-     */
-    public static String toLowerFirstChar(final String str)
-    {
-        return Character.toLowerCase(str.charAt(0)) + str.substring(1);
-    }
-
     /**
      * Format a String as a property name.
      *
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/cpp/CppGenerator.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/cpp/CppGenerator.java
@@ -33,9 +33,14 @@
 import java.util.Formatter;
 import java.util.List;
 
+import static uk.co.real_logic.sbe.generation.Generators.toLowerFirstChar;
+import static uk.co.real_logic.sbe.generation.Generators.toUpperFirstChar;
 import static uk.co.real_logic.sbe.generation.cpp.CppUtil.*;
 import static uk.co.real_logic.sbe.ir.GenerationUtil.*;
 
+/**
+ * Codec generator for the C++11 programming language with conditional complication for C++14 and C++17 features.
+ */
 @SuppressWarnings("MethodLength")
 public class CppGenerator implements CodeGenerator
 {
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/cpp/CppUtil.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/cpp/CppUtil.java
@@ -23,6 +23,9 @@
 import java.util.EnumMap;
 import java.util.Map;
 
+import static uk.co.real_logic.sbe.generation.Generators.toLowerFirstChar;
+import static uk.co.real_logic.sbe.generation.Generators.toUpperFirstChar;
+
 /**
  * Utilities for mapping between IR and the C++ language.
  */
@@ -56,28 +59,6 @@ public static String cppTypeName(final PrimitiveType primitiveType)
         return PRIMITIVE_TYPE_STRING_ENUM_MAP.get(primitiveType);
     }
 
-    /**
-     * Uppercase the first character of a given String.
-     *
-     * @param str to have the first character upper cased.
-     * @return a new String with the first character in uppercase.
-     */
-    public static String toUpperFirstChar(final String str)
-    {
-        return Character.toUpperCase(str.charAt(0)) + str.substring(1);
-    }
-
-    /**
-     * Lowercase the first character of a given String.
-     *
-     * @param str to have the first character upper cased.
-     * @return a new String with the first character in uppercase.
-     */
-    public static String toLowerFirstChar(final String str)
-    {
-        return Character.toLowerCase(str.charAt(0)) + str.substring(1);
-    }
-
     /**
      * Format a String as a property name.
      *
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/csharp/CSharp.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/csharp/CSharp.java
@@ -19,6 +19,9 @@
 import uk.co.real_logic.sbe.generation.TargetCodeGenerator;
 import uk.co.real_logic.sbe.ir.Ir;
 
+/**
+ * {@link CodeGenerator} factory for the CSharp target programming language.
+ */
 public class CSharp implements TargetCodeGenerator
 {
     public CodeGenerator newInstance(final Ir ir, final String outputDir)
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/csharp/CSharpGenerator.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/csharp/CSharpGenerator.java
@@ -30,11 +30,16 @@
 import java.util.ArrayList;
 import java.util.List;
 
+import static uk.co.real_logic.sbe.generation.Generators.toLowerFirstChar;
+import static uk.co.real_logic.sbe.generation.Generators.toUpperFirstChar;
 import static uk.co.real_logic.sbe.generation.csharp.CSharpUtil.*;
 import static uk.co.real_logic.sbe.ir.GenerationUtil.collectVarData;
 import static uk.co.real_logic.sbe.ir.GenerationUtil.collectGroups;
 import static uk.co.real_logic.sbe.ir.GenerationUtil.collectFields;
 
+/**
+ * Codec generator for the CSharp programming language.
+ */
 @SuppressWarnings("MethodLength")
 public class CSharpGenerator implements CodeGenerator
 {
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/csharp/CSharpUtil.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/csharp/CSharpUtil.java
@@ -21,6 +21,8 @@
 import java.util.EnumMap;
 import java.util.Map;
 
+import static uk.co.real_logic.sbe.generation.Generators.toUpperFirstChar;
+
 /**
  * Utilities for mapping between IR and the C# language.
  */
@@ -57,28 +59,6 @@ public static String cSharpTypeName(final PrimitiveType primitiveType)
         return PRIMITIVE_TYPE_STRING_ENUM_MAP.get(primitiveType);
     }
 
-    /**
-     * Uppercase the first character of a given String.
-     *
-     * @param str to have the first character upper cased.
-     * @return a new String with the first character in uppercase.
-     */
-    public static String toUpperFirstChar(final String str)
-    {
-        return Character.toUpperCase(str.charAt(0)) + str.substring(1);
-    }
-
-    /**
-     * Lowercase the first character of a given String.
-     *
-     * @param str to have the first character upper cased.
-     * @return a new String with the first character in uppercase.
-     */
-    public static String toLowerFirstChar(final String str)
-    {
-        return Character.toLowerCase(str.charAt(0)) + str.substring(1);
-    }
-
     /**
      * Format a String as a property name.
      *
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/golang/GolangGenerator.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/golang/GolangGenerator.java
@@ -33,11 +33,15 @@
 import java.util.TreeSet;
 
 import static uk.co.real_logic.sbe.PrimitiveType.CHAR;
+import static uk.co.real_logic.sbe.generation.Generators.toUpperFirstChar;
 import static uk.co.real_logic.sbe.generation.golang.GolangUtil.*;
 import static uk.co.real_logic.sbe.ir.GenerationUtil.collectVarData;
 import static uk.co.real_logic.sbe.ir.GenerationUtil.collectGroups;
 import static uk.co.real_logic.sbe.ir.GenerationUtil.collectFields;
 
+/**
+ * Codec generator for the Go Lang programming language.
+ */
 @SuppressWarnings("MethodLength")
 public class GolangGenerator implements CodeGenerator
 {
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/golang/GolangUtil.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/golang/GolangUtil.java
@@ -22,6 +22,8 @@
 import java.util.EnumMap;
 import java.util.Map;
 
+import static uk.co.real_logic.sbe.generation.Generators.toUpperFirstChar;
+
 /**
  * Utilities for mapping between IR and the Golang language.
  */
@@ -84,28 +86,6 @@ public static String golangMarshalType(final PrimitiveType primitiveType)
         return MARSHAL_TYPE_BY_PRIMITIVE_TYPE_MAP.get(primitiveType);
     }
 
-    /**
-     * Uppercase the first character of a given String.
-     *
-     * @param str to have the first character upper cased.
-     * @return a new String with the first character in uppercase.
-     */
-    public static String toUpperFirstChar(final String str)
-    {
-        return Character.toUpperCase(str.charAt(0)) + str.substring(1);
-    }
-
-    /**
-     * Lowercase the first character of a given String.
-     *
-     * @param str to have the first character upper cased.
-     * @return a new String with the first character in uppercase.
-     */
-    public static String toLowerFirstChar(final String str)
-    {
-        return Character.toLowerCase(str.charAt(0)) + str.substring(1);
-    }
-
     /**
      * Format a String as a property name.
      *
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/java/JavaGenerator.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/java/JavaGenerator.java
@@ -36,6 +36,9 @@
 import static uk.co.real_logic.sbe.generation.java.JavaUtil.*;
 import static uk.co.real_logic.sbe.ir.GenerationUtil.*;
 
+/**
+ * Generate codecs for the Java 8 programming language.
+ */
 @SuppressWarnings("MethodLength")
 public class JavaGenerator implements CodeGenerator
 {
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/java/JavaUtil.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/generation/java/JavaUtil.java
@@ -32,7 +32,7 @@
 import static java.lang.reflect.Modifier.STATIC;
 
 /**
- * Utilities for mapping between IR and the Java language.
+ * Utilities for mapping between {@link uk.co.real_logic.sbe.ir.Ir} and the Java language.
  */
 public class JavaUtil
 {
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/MessageComponents.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/MessageComponents.java
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/Signal.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/ir/Signal.java
diff --git a/sbe-tool/src/main/java/uk/co/real_logic/sbe/json/JsonTokenListener.java b/sbe-tool/src/main/java/uk/co/real_logic/sbe/json/JsonTokenListener.java

Original file line number	Diff line number	Diff line change
`@@ -27,6 +27,9 @@`
`27`	`27`	`import java.util.Map;`
`28`	`28`	`import java.util.Set;`
`29`	`29`
	`30`	`+/**`
	`31`	`+ * Selects sorted methods of a class that are annotated with {@link GroupOrder}.`
	`32`	`+ */`
`30`	`33`	`public class MethodSelector`
`31`	`34`	`{`
`32`	`35`	`private final Set<String> ignoredMethods;`
Original file line number	Diff line number	Diff line change
`@@ -21,6 +21,9 @@`
`21`	`21`	`import java.util.List;`
`22`	`22`	`import java.util.function.BiConsumer;`
`23`	`23`
	`24`	`+/**`
	`25`	`+ * Common operations available to all {@link CodeGenerator}s.`
	`26`	`+ */`
`24`	`27`	`public class Generators`
`25`	`28`	`{`
`26`	`29`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -27,8 +27,15 @@`
`27`	`27`
`28`	`28`	`import static uk.co.real_logic.sbe.SbeTool.*;`
`29`	`29`
	`30`	`+/**`
	`31`	`+ * Loader for {@link CodeGenerator}s which target a language. This provide convenient short names rather than the`
	`32`	`+ * fully qualified class name of the generator.`
	`33`	`+ */`
`30`	`34`	`public enum TargetCodeGeneratorLoader implements TargetCodeGenerator`
`31`	`35`	`{`
	`36`	`+ /**`
	`37`	`+ * Generates codecs for the Java 8 programming language.`
	`38`	`+ */`
`32`	`39`	`JAVA()`
`33`	`40`	`{`
`34`	`41`	`public CodeGenerator newInstance(final Ir ir, final String outputDir)`
`@@ -44,6 +51,9 @@ public CodeGenerator newInstance(final Ir ir, final String outputDir)`
`44`	`51`	`}`
`45`	`52`	`},`
`46`	`53`
	`54`	`+ /**`
	`55`	`+ * Generates codecs for the C11 programming language.`
	`56`	`+ */`
`47`	`57`	`C()`
`48`	`58`	`{`
`49`	`59`	`public CodeGenerator newInstance(final Ir ir, final String outputDir)`
`@@ -52,6 +62,9 @@ public CodeGenerator newInstance(final Ir ir, final String outputDir)`
`52`	`62`	`}`
`53`	`63`	`},`
`54`	`64`
	`65`	`+ /**`
	`66`	`+ * Generates codecs for the C++11 programming language with some conditional includes for C++14 and C++17.`
	`67`	`+ */`
`55`	`68`	`CPP()`
`56`	`69`	`{`
`57`	`70`	`public CodeGenerator newInstance(final Ir ir, final String outputDir)`
`@@ -60,6 +73,9 @@ public CodeGenerator newInstance(final Ir ir, final String outputDir)`
`60`	`73`	`}`
`61`	`74`	`},`
`62`	`75`
	`76`	`+ /**`
	`77`	`+ * Generates codecs for the Go programming language.`
	`78`	`+ */`
`63`	`79`	`GOLANG()`
`64`	`80`	`{`
`65`	`81`	`public CodeGenerator newInstance(final Ir ir, final String outputDir)`
Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,9 @@`
`19`	`19`	`import uk.co.real_logic.sbe.generation.TargetCodeGenerator;`
`20`	`20`	`import uk.co.real_logic.sbe.ir.Ir;`
`21`	`21`
	`22`	`+/**`
	`23`	`+ * {@link CodeGenerator} factory for the CSharp target programming language.`
	`24`	`+ */`
`22`	`25`	`public class CSharp implements TargetCodeGenerator`
`23`	`26`	`{`
`24`	`27`	`public CodeGenerator newInstance(final Ir ir, final String outputDir)`