From 78d661f781c7d67d708c43aac45ca41201993112 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Sebastian=20Ho=C3=9F?= <sebhoss@pm.me>
Date: Thu, 1 Apr 2021 23:57:52 +0200
Subject: [PATCH] fix #106 add description field

---
 .../wtf/metio/yosql/codegen/blocks/DefaultJavadoc.java     |  8 ++++++++
 .../main/java/wtf/metio/yosql/models/meta/data/Sql.java    | 11 +++++++++++
 yosql-website/content/sql/frontmatter.md                   | 14 +++++++++++++-
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/yosql-codegen/yosql-codegen-blocks/src/main/java/wtf/metio/yosql/codegen/blocks/DefaultJavadoc.java b/yosql-codegen/yosql-codegen-blocks/src/main/java/wtf/metio/yosql/codegen/blocks/DefaultJavadoc.java
index 19355342..c5606529 100644
--- a/yosql-codegen/yosql-codegen-blocks/src/main/java/wtf/metio/yosql/codegen/blocks/DefaultJavadoc.java
+++ b/yosql-codegen/yosql-codegen-blocks/src/main/java/wtf/metio/yosql/codegen/blocks/DefaultJavadoc.java
@@ -12,12 +12,15 @@ import de.xn__ho_hia.javapoet.TypeGuesser;
 import wtf.metio.yosql.codegen.api.Javadoc;
 import wtf.metio.yosql.internals.jdk.Strings;
 import wtf.metio.yosql.models.immutables.FilesConfiguration;
+import wtf.metio.yosql.models.immutables.SqlConfiguration;
 import wtf.metio.yosql.models.immutables.SqlStatement;
 import wtf.metio.yosql.models.sql.ResultRowConverter;
 
 import java.util.List;
 import java.util.Objects;
 
+import static java.util.function.Predicate.not;
+
 public final class DefaultJavadoc implements Javadoc {
 
     private final FilesConfiguration files;
@@ -55,6 +58,11 @@ public final class DefaultJavadoc implements Javadoc {
     @Override
     public CodeBlock methodJavadoc(final List<SqlStatement> statements) {
         final var builder = CodeBlock.builder();
+        statements.stream()
+                .map(SqlStatement::getConfiguration)
+                .map(SqlConfiguration::description)
+                .filter(not(Strings::isBlank))
+                .forEach(description -> builder.add("<p>$L<p>\n", description));
         if (statements.size() > 1) {
             builder.add("<p>Executes one of the following statements:</p>");
         } else {
diff --git a/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/data/Sql.java b/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/data/Sql.java
index 2761313d..b28b7820 100644
--- a/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/data/Sql.java
+++ b/yosql-models/yosql-models-meta/src/main/java/wtf/metio/yosql/models/meta/data/Sql.java
@@ -46,6 +46,7 @@ public final class Sql {
         return List.of(
                 repository(),
                 name(),
+                description(),
                 vendor(),
                 type(),
                 returningMode(),
@@ -93,6 +94,16 @@ public final class Sql {
                 .build();
     }
 
+    private static ConfigurationSetting description() {
+        return ConfigurationSetting.builder()
+                .setName("description")
+                .setDescription("The description for the SQL statement")
+                .setType(TypicalTypes.STRING)
+                .setValue("")
+                .setImmutableAnnotations(List.of(jsonProperty("description")))
+                .build();
+    }
+
     private static ConfigurationSetting vendor() {
         return ConfigurationSetting.builder()
                 .setName("vendor")
diff --git a/yosql-website/content/sql/frontmatter.md b/yosql-website/content/sql/frontmatter.md
index 74037f6b..4ec02962 100644
--- a/yosql-website/content/sql/frontmatter.md
+++ b/yosql-website/content/sql/frontmatter.md
@@ -15,6 +15,7 @@ Each SQL statement can have an optional front matter section written in YAML tha
 
 ```sql
 -- name: someName
+-- description: Retrieves a single user
 -- repository: com.example.persistence.YourRepository
 -- vendor: H2
 -- parameters:
@@ -37,7 +38,7 @@ While parsing your `.sql` files, `YoSQL` will strip the SQL comment prefix (`--`
 
 ## name
 
-The `name` field can be used to change the name of a SQL statement. Typically, the name is auto-detected from the `.sql` file name, however if you want to place multiple SQL statements in one file, use `name` to give each statement a unique name instead of relying on the auto-numbering `YoSQL` is using by default.
+The `name` field can be used to change the name of an SQL statement. Typically, the name is auto-detected from the `.sql` file name, however if you want to place multiple SQL statements in one file, use `name` to give each statement a unique name instead of relying on the auto-numbering `YoSQL` is using by default.
 
 ```sql
 -- name: someName
@@ -46,6 +47,17 @@ FROM    users
 WHERE   id = :userId
 ```
 
+## description
+
+The `description` field can be used to add a description to your SQL statements that will be part of generated Javadocs.
+
+```sql
+-- description: Retrieves a single user
+SELECT  *
+FROM    users
+WHERE   id = :userId
+```
+
 ## repository
 
 The `repository` field can be used to change which repository will contain the SQL statement. By default, `YoSQL` will auto-detect the repository based on the location of the `.sql` file. In case you want to structure your `.sql` files in a specific way, but move some SQL statements to specific repositories, use `repository` together with the fully-qualified name of the target repository.
-- 
2.11.4.GIT