fix #98 generate javadoc for methods

metio · Apr 1, 2021 · 53e7df7 · 53e7df7
1 parent 78d661f
commit 53e7df7
Show file tree

Hide file tree

Showing 15 changed files with 259 additions and 92 deletions.
diff --git a/yosql-codegen/yosql-codegen-api/src/main/java/wtf/metio/yosql/codegen/api/Javadoc.java b/yosql-codegen/yosql-codegen-api/src/main/java/wtf/metio/yosql/codegen/api/Javadoc.java
@@ -28,9 +28,10 @@ public interface Javadoc {
      * Creates typical javadoc documentation for generated methods.
      *
      * @param statements The statements of the method.
+     * @param configuration The configuration toggle to use.
      * @return The javadoc for a single method based on the given statements.
      */
-    CodeBlock methodJavadoc(List<SqlStatement> statements);
+    CodeBlock methodJavadoc(List<SqlStatement> statements, String configuration);
 
     /**
      * Creates typical javadoc documentation for generated fields.

diff --git a/yosql-codegen/yosql-codegen-api/src/main/java/wtf/metio/yosql/codegen/api/Methods.java b/yosql-codegen/yosql-codegen-api/src/main/java/wtf/metio/yosql/codegen/api/Methods.java
@@ -17,16 +17,76 @@
  */
 public interface Methods {
 
+    /**
+     * Create a new builder for public methods.
+     *
+     * @param name The name of the method.
+     * @return A method builder preconfigured for public methods.
+     */
     MethodSpec.Builder publicMethod(String name);
 
     /**
-     * Prepare {@link MethodSpec} with Javadoc
+     * Prepare {@link MethodSpec} with Javadoc for standard methods.
+     *
+     * @param name       The name of the generated method.
+     * @param statements The SQL statements used for Javadocs
+     * @return The resulting builder for the MethodSpec.
+     */
+    MethodSpec.Builder standardMethod(String name, List<SqlStatement> statements);
+
+    /**
+     * Prepare {@link MethodSpec} with Javadoc for batch methods.
+     *
+     * @param name       The name of the generated method.
+     * @param statements The SQL statements used for Javadocs
+     * @return The resulting builder for the MethodSpec.
+     */
+    MethodSpec.Builder batchMethod(String name, List<SqlStatement> statements);
+
+    /**
+     * Prepare {@link MethodSpec} with Javadoc for eager stream methods.
+     *
+     * @param name       The name of the generated method.
+     * @param statements The SQL statements used for Javadocs
+     * @return The resulting builder for the MethodSpec.
+     */
+    MethodSpec.Builder streamEagerMethod(String name, List<SqlStatement> statements);
+
+    /**
+     * Prepare {@link MethodSpec} with Javadoc for lazy stream methods.
+     *
+     * @param name       The name of the generated method.
+     * @param statements The SQL statements used for Javadocs
+     * @return The resulting builder for the MethodSpec.
+     */
+    MethodSpec.Builder streamLazyMethod(String name, List<SqlStatement> statements);
+
+    /**
+     * Prepare {@link MethodSpec} with Javadoc for rxjava methods.
+     *
+     * @param name       The name of the generated method.
+     * @param statements The SQL statements used for Javadocs
+     * @return The resulting builder for the MethodSpec.
+     */
+    MethodSpec.Builder rxJavaMethod(String name, List<SqlStatement> statements);
+
+    /**
+     * Prepare {@link MethodSpec} with Javadoc for reactor methods.
+     *
+     * @param name       The name of the generated method.
+     * @param statements The SQL statements used for Javadocs
+     * @return The resulting builder for the MethodSpec.
+     */
+    MethodSpec.Builder reactorMethod(String name, List<SqlStatement> statements);
+
+    /**
+     * Prepare {@link MethodSpec} with Javadoc for mutiny methods.
      *
      * @param name       The name of the generated method.
      * @param statements The SQL statements used for Javadocs
      * @return The resulting builder for the MethodSpec.
      */
-    MethodSpec.Builder publicMethod(String name, List<SqlStatement> statements);
+    MethodSpec.Builder mutinyMethod(String name, List<SqlStatement> statements);
 
     MethodSpec.Builder implementation(String name);
 

diff --git a/...gen/yosql-codegen-blocks/src/main/java/wtf/metio/yosql/codegen/blocks/DefaultJavadoc.java b/...gen/yosql-codegen-blocks/src/main/java/wtf/metio/yosql/codegen/blocks/DefaultJavadoc.java
@@ -56,7 +56,7 @@ public CodeBlock fieldJavaDoc(final SqlStatement statement) {
     }
 
     @Override
-    public CodeBlock methodJavadoc(final List<SqlStatement> statements) {
+    public CodeBlock methodJavadoc(final List<SqlStatement> statements, final String configuration) {
         final var builder = CodeBlock.builder();
         statements.stream()
                 .map(SqlStatement::getConfiguration)
@@ -74,7 +74,7 @@ public CodeBlock methodJavadoc(final List<SqlStatement> statements) {
                     builder.add("\n\n<p>Fallback for other databases:</p>");
                 }
             } else {
-                builder.add("\n\n<p>Vendor: $N</p>", statement.getConfiguration().vendor());
+                builder.add("\n\n<p>Vendor: $L</p>", statement.getConfiguration().vendor());
             }
             builder.add("\n<pre>\n$L</pre>", statement.getRawStatement());
         }
@@ -87,6 +87,7 @@ public CodeBlock methodJavadoc(final List<SqlStatement> statements) {
                 .map(input::relativize)
                 .forEach(path -> builder.add("<li>$L</li>\n", path));
         builder.add("</ul>\n");
+        builder.add("<p>Disable generating this method by setting <strong>$L</strong> to <strong>false</strong></p>\n", configuration);
         statements.stream()
                 .map(SqlStatement::getConfiguration)
                 .flatMap(config -> config.resultRowConverter().stream())
@@ -99,7 +100,7 @@ public CodeBlock methodJavadoc(final List<SqlStatement> statements) {
                 .map(TypeGuesser::guessTypeName)
                 .filter(type -> !type.isPrimitive())
                 .filter(type -> !type.isBoxedPrimitive())
-                .forEach(type -> builder.add("\n@see $S", type));
+                .forEach(type -> builder.add("\n@see $L", type));
         return builder.build();
     }
 

diff --git a/...gen/yosql-codegen-blocks/src/main/java/wtf/metio/yosql/codegen/blocks/DefaultMethods.java b/...gen/yosql-codegen-blocks/src/main/java/wtf/metio/yosql/codegen/blocks/DefaultMethods.java
@@ -39,15 +39,45 @@ public MethodSpec.Builder publicMethod(final String name) {
                 .addAnnotations(annotations.generatedMethod());
     }
 
-    @Override
-    public MethodSpec.Builder publicMethod(final String name, final List<SqlStatement> statements) {
+    public MethodSpec.Builder standardMethod(final String name, final List<SqlStatement> statements) {
+        return publicMethod(name, statements, "generateStandardApi");
+    }
+
+    public MethodSpec.Builder batchMethod(final String name, final List<SqlStatement> statements) {
+        return publicMethod(name, statements, "generateBatchApi");
+    }
+
+    public MethodSpec.Builder streamEagerMethod(final String name, final List<SqlStatement> statements) {
+        return publicMethod(name, statements, "generateStreamEagerApi");
+    }
+
+    public MethodSpec.Builder streamLazyMethod(final String name, final List<SqlStatement> statements) {
+        return publicMethod(name, statements, "generateStreamLazyApi");
+    }
+
+    public MethodSpec.Builder rxJavaMethod(final String name, final List<SqlStatement> statements) {
+        return publicMethod(name, statements, "generateRxJavaApi");
+    }
+
+    public MethodSpec.Builder reactorMethod(final String name, final List<SqlStatement> statements) {
+        return publicMethod(name, statements, "generateReactorApi");
+    }
+
+    public MethodSpec.Builder mutinyMethod(final String name, final List<SqlStatement> statements) {
+        return publicMethod(name, statements, "generateMutinyApi");
+    }
+
+    public MethodSpec.Builder publicMethod(
+            final String name, 
+            final List<SqlStatement> statements, 
+            final String configuration) {
         final var modifiers = java.useFinal()
                 ? List.of(Modifier.PUBLIC, Modifier.FINAL)
                 : List.of(Modifier.PUBLIC);
         return MethodSpec.methodBuilder(name)
                 .addModifiers(modifiers)
                 .addAnnotations(annotations.generatedMethod())
-                .addJavadoc(javadoc.methodJavadoc(statements));
+                .addJavadoc(javadoc.methodJavadoc(statements, configuration));
     }
 
     @Override

diff --git a/...yosql-codegen-blocks/src/test/java/wtf/metio/yosql/codegen/blocks/DefaultJavadocTest.java b/...yosql-codegen-blocks/src/test/java/wtf/metio/yosql/codegen/blocks/DefaultJavadocTest.java
@@ -43,11 +43,12 @@ Generated based on the following file(s):
     void shouldGenerateMethodComment() {
         Assertions.assertEquals("""
                 <p>Executes the following statement:</p>
-                
+                                
                 <p>Generated based on the following file(s):</p>
                 <ul>
                 </ul>
-                """, generator.methodJavadoc(List.of()).toString());
+                <p>Disable generating this method by setting <strong></strong> to <strong>false</strong></p>
+                """, generator.methodJavadoc(List.of(), "").toString());
     }
 
     @Test

diff --git a/...l-dao/yosql-dao-jdbc/src/main/java/wtf/metio/yosql/dao/jdbc/JdbcBatchMethodGenerator.java b/...l-dao/yosql-dao-jdbc/src/main/java/wtf/metio/yosql/dao/jdbc/JdbcBatchMethodGenerator.java
@@ -46,7 +46,7 @@ public JdbcBatchMethodGenerator(
     public MethodSpec batchWriteMethod(
             final SqlConfiguration configuration,
             final List<SqlStatement> statements) {
-        return methods.publicMethod(configuration.batchName(), statements)
+        return methods.batchMethod(configuration.batchName(), statements)
                 .returns(TypicalTypes.ARRAY_OF_INTS)
                 .addParameters(parameters.asBatchParameterSpecs(configuration.parameters()))
                 .addExceptions(transformer.sqlException(configuration))

diff --git a/...yosql-dao-jdbc/src/main/java/wtf/metio/yosql/dao/jdbc/JdbcJava8StreamMethodGenerator.java b/...yosql-dao-jdbc/src/main/java/wtf/metio/yosql/dao/jdbc/JdbcJava8StreamMethodGenerator.java
@@ -65,7 +65,7 @@ public MethodSpec streamEagerMethod(
         final var resultType = TypeGuesser.guessTypeName(converter.resultType());
         final var listOfResults = TypicalTypes.listOf(resultType);
         final var streamOfResults = TypicalTypes.streamOf(resultType);
-        return methods.publicMethod(configuration.streamEagerName(), statements)
+        return methods.streamEagerMethod(configuration.streamEagerName(), statements)
                 .returns(streamOfResults)
                 .addParameters(parameters.asParameterSpecs(configuration.parameters()))
                 .addExceptions(transformer.sqlException(configuration))
@@ -92,7 +92,7 @@ public MethodSpec streamLazyMethod(
         final var converter = configuration.resultRowConverter().orElse(config.defaultConverter().orElseThrow());
         final var resultType = TypeGuesser.guessTypeName(converter.resultType());
         final var streamOfResults = TypicalTypes.streamOf(resultType);
-        return methods.publicMethod(configuration.streamLazyName(), statements)
+        return methods.streamLazyMethod(configuration.streamLazyName(), statements)
                 .returns(streamOfResults)
                 .addParameters(parameters.asParameterSpecs(configuration.parameters()))
                 .addExceptions(transformer.sqlException(configuration))

diff --git a/...-dao/yosql-dao-jdbc/src/main/java/wtf/metio/yosql/dao/jdbc/JdbcRxJavaMethodGenerator.java b/...-dao/yosql-dao-jdbc/src/main/java/wtf/metio/yosql/dao/jdbc/JdbcRxJavaMethodGenerator.java
@@ -62,7 +62,7 @@ public MethodSpec rxJava2ReadMethod(
         final var generator = createFlowGenerator(converter);
         final var disposer = createFlowDisposer();
 
-        return methods.publicMethod(configuration.flowableName(), statements)
+        return methods.rxJavaMethod(configuration.flowableName(), statements)
                 .returns(flowReturn)
                 .addParameters(parameters.asParameterSpecs(configuration.parameters()))
                 .addCode(logging.entering(configuration.repository(),

diff --git a/...ao/yosql-dao-jdbc/src/main/java/wtf/metio/yosql/dao/jdbc/JdbcStandardMethodGenerator.java b/...ao/yosql-dao-jdbc/src/main/java/wtf/metio/yosql/dao/jdbc/JdbcStandardMethodGenerator.java
@@ -55,7 +55,7 @@ public MethodSpec standardReadMethod(
         final var resultType = TypeGuesser.guessTypeName(converter.resultType());
         final var listOfResults = TypicalTypes.listOf(resultType);
         final var methodName = configuration.name();
-        return methods.publicMethod(methodName, statements)
+        return methods.standardMethod(methodName, statements)
                 .returns(listOfResults)
                 .addParameters(parameters.asParameterSpecs(configuration.parameters()))
                 .addExceptions(jdbcTransformer.sqlException(configuration))
@@ -80,7 +80,7 @@ public MethodSpec standardWriteMethod(
             final SqlConfiguration configuration,
             final List<SqlStatement> statements) {
         final var methodName = configuration.name();
-        return methods.publicMethod(methodName, statements)
+        return methods.standardMethod(methodName, statements)
                 .returns(int.class)
                 .addExceptions(jdbcTransformer.sqlException(configuration))
                 .addParameters(parameters.asParameterSpecs(configuration.parameters()))
@@ -104,7 +104,7 @@ public MethodSpec standardCallMethod(
         final var resultType = TypeGuesser.guessTypeName(converter.resultType());
         final var listOfResults = TypicalTypes.listOf(resultType);
         final var methodName = configuration.name();
-        return methods.publicMethod(methodName, statements)
+        return methods.standardMethod(methodName, statements)
                 .returns(listOfResults)
                 .addParameters(parameters.asParameterSpecs(configuration.parameters()))
                 .addExceptions(jdbcTransformer.sqlException(configuration))

diff --git a/...o/yosql-dao-jdbc/src/test/java/wtf/metio/yosql/dao/jdbc/JdbcBatchMethodGeneratorTest.java b/...o/yosql-dao-jdbc/src/test/java/wtf/metio/yosql/dao/jdbc/JdbcBatchMethodGeneratorTest.java
@@ -37,8 +37,9 @@ public String batchWriteMethodExpectation() {
                      * <ul>
                      * <li>data/queryData.sql</li>
                      * </ul>
+                     * <p>Disable generating this method by setting <strong>generateBatchApi</strong> to <strong>false</strong></p>
                      *
-                     * @see "com.example.util.ResultRow"
+                     * @see com.example.util.ResultRow
                      */
                     @javax.annotation.processing.Generated(
                         value = "YoSQL",
@@ -101,8 +102,9 @@ public String batchWriteMethodExpectation() {
                      * <ul>
                      * <li>data/queryData.sql</li>
                      * </ul>
+                     * <p>Disable generating this method by setting <strong>generateBatchApi</strong> to <strong>false</strong></p>
                      *
-                     * @see "com.example.util.ResultRow"
+                     * @see com.example.util.ResultRow
                      */
                     @javax.annotation.processing.Generated(
                         value = "YoSQL",
@@ -165,8 +167,9 @@ public String batchWriteMethodExpectation() {
                      * <ul>
                      * <li>data/queryData.sql</li>
                      * </ul>
+                     * <p>Disable generating this method by setting <strong>generateBatchApi</strong> to <strong>false</strong></p>
                      *
-                     * @see "com.example.util.ResultRow"
+                     * @see com.example.util.ResultRow
                      */
                     @javax.annotation.processing.Generated(
                         value = "YoSQL",
@@ -229,8 +232,9 @@ public String batchWriteMethodExpectation() {
                      * <ul>
                      * <li>data/queryData.sql</li>
                      * </ul>
+                     * <p>Disable generating this method by setting <strong>generateBatchApi</strong> to <strong>false</strong></p>
                      *
-                     * @see "com.example.util.ResultRow"
+                     * @see com.example.util.ResultRow
                      */
                     @javax.annotation.processing.Generated(
                         value = "YoSQL",
@@ -293,8 +297,9 @@ public String batchWriteMethodExpectation() {
                      * <ul>
                      * <li>data/queryData.sql</li>
                      * </ul>
+                     * <p>Disable generating this method by setting <strong>generateBatchApi</strong> to <strong>false</strong></p>
                      *
-                     * @see "com.example.util.ResultRow"
+                     * @see com.example.util.ResultRow
                      */
                     @javax.annotation.processing.Generated(
                         value = "YoSQL",
@@ -357,8 +362,9 @@ public String batchWriteMethodExpectation() {
                      * <ul>
                      * <li>data/queryData.sql</li>
                      * </ul>
+                     * <p>Disable generating this method by setting <strong>generateBatchApi</strong> to <strong>false</strong></p>
                      *
-                     * @see "com.example.util.ResultRow"
+                     * @see com.example.util.ResultRow
                      */
                     @javax.annotation.processing.Generated(
                         value = "YoSQL",
@@ -421,8 +427,9 @@ public String batchWriteMethodExpectation() {
                      * <ul>
                      * <li>data/queryData.sql</li>
                      * </ul>
+                     * <p>Disable generating this method by setting <strong>generateBatchApi</strong> to <strong>false</strong></p>
                      *
-                     * @see "com.example.util.ResultRow"
+                     * @see com.example.util.ResultRow
                      */
                     @javax.annotation.processing.Generated(
                         value = "YoSQL",
@@ -485,8 +492,9 @@ public String batchWriteMethodExpectation() {
                      * <ul>
                      * <li>data/queryData.sql</li>
                      * </ul>
+                     * <p>Disable generating this method by setting <strong>generateBatchApi</strong> to <strong>false</strong></p>
                      *
-                     * @see "com.example.util.ResultRow"
+                     * @see com.example.util.ResultRow
                      */
                     @javax.annotation.processing.Generated(
                         value = "YoSQL",
@@ -549,8 +557,9 @@ public String batchWriteMethodExpectation() {
                      * <ul>
                      * <li>data/queryData.sql</li>
                      * </ul>
+                     * <p>Disable generating this method by setting <strong>generateBatchApi</strong> to <strong>false</strong></p>
                      *
-                     * @see "com.example.util.ResultRow"
+                     * @see com.example.util.ResultRow
                      */
                     @javax.annotation.processing.Generated(
                         value = "YoSQL",