Update Javadocs with @snippet tags.

Change-Id: I22f440c6ced5b90cdebc1fdf068171e7baad180f

10 files changed, 88 insertions, 52 deletions

diff --git a/.gitignore b/.gitignore
index 8cc2382..8d8bbbe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,7 +9,9 @@ build/
 target/
 
 .envrc
+.flattened-pom.xml
 
 *~
 *.class
 *.iml
+*.versionsBackup
diff --git a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/KeyValueParameter.java b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/KeyValueParameter.java
index d8ab58d..ef5d06a 100644
--- a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/KeyValueParameter.java
+++ b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/KeyValueParameter.java
@@ -20,20 +20,20 @@ import javax.json.JsonValue;
  *
  * <p><strong>Example:</strong>
  *
- * <pre>{@code
+ * {@snippet :
  * logger.infof("Application starting.", StructuredParameter.of("version", "1.0"));
- * }</pre>
+ * }
  *
- * Result:
+ * <p>Result:
  *
- * <pre>{@code
+ * {@snippet lang="json" :
  * {
  *   "jsonPayload": {
  *     "message": "Application starting.",
  *     "version": "1.0"
  *   }
  * }
- * }</pre>
+ * }
  *
  * @see Label
  * @see StructuredParameter
diff --git a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Label.java b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Label.java
index b46862e..d5a9000 100644
--- a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Label.java
+++ b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/Label.java
@@ -14,20 +14,20 @@ import java.util.Objects;
  *
  * <p><strong>Example:</strong>
  *
- * <pre>{@code
+ * {@snippet :
  * logger.logf("Request rejected: unauthorized.", Label.of("requestId", "123"));
- * }</pre>
+ * }
  *
- * Result:
+ * <p>Result:
  *
- * <pre>{@code
+ * {@snippet lang="json" :
  * {
  *   "textPayload": "Request rejected: unauthorized.",
  *   "labels": {
  *     "requestId": "123"
  *   }
  * }
- * }</pre>
+ * }
  *
  * @see KeyValueParameter
  * @see StructuredParameter
diff --git a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/LabelProvider.java b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/LabelProvider.java
index 0588fbb..7cca6a0 100644
--- a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/LabelProvider.java
+++ b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/LabelProvider.java
@@ -17,7 +17,7 @@ import java.util.Collection;
  *
  * <p><strong>Example:</strong>
  *
- * <pre>{@code
+ * {@snippet :
  * @Singleton
  * @Unremovable
  * public final class RequestIdLabelProvider implements LabelProvider {
@@ -27,18 +27,18 @@ import java.util.Collection;
  *     return List.of(Label.of("requestId", RequestContext.current().getRequestId()));
  *   }
  * }
- * }</pre>
+ * }
  *
- * Result:
+ * <p>Result:
  *
- * <pre>{@code
+ * {@snippet lang="json" :
  * {
  *   "textPayload": "Request rejected: unauthorized.",
  *   "labels": {
  *     "requestId": "123"
  *   }
  * }
- * }</pre>
+ * }
  *
  * @see StructuredParameterProvider
  */
diff --git a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameter.java b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameter.java
index 9bc3c11..c233158 100644
--- a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameter.java
+++ b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameter.java
@@ -14,12 +14,12 @@ import javax.json.JsonObjectBuilder;
  *
  * <p>Example:
  *
- * <pre>{@code
+ * {@snippet :
  * StructuredParameter p1 = ...;
  * StructuredParameter p2 = ...;
  *
  * logger.logf("Something interesting happened.", p1, p2);
- * }</pre>
+ * }
  *
  * @see KeyValueParameter
  * @see Label
diff --git a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameterProvider.java b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameterProvider.java
index 70bdce6..b8f80ce 100644
--- a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameterProvider.java
+++ b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameterProvider.java
@@ -15,7 +15,7 @@ package eu.mulk.quarkus.googlecloud.jsonlogging;
  *
  * <p><strong>Example:</strong>
  *
- * <pre>{@code
+ * {@snippet :
  * @Singleton
  * @Unremovable
  * public final class TraceLogParameterProvider implements StructuredParameterProvider {
@@ -28,11 +28,11 @@ package eu.mulk.quarkus.googlecloud.jsonlogging;
  *     return () -> b;
  *   }
  * }
- * }</pre>
+ * }
  *
  * Result:
  *
- * <pre>{@code
+ * {@snippet lang="json" :
  * {
  *   "jsonPayload": {
  *     "message": "Request rejected: unauthorized.",
@@ -40,7 +40,7 @@ package eu.mulk.quarkus.googlecloud.jsonlogging;
  *     "spanId": "c7431b14630b633d"
  *   }
  * }
- * }</pre>
+ * }
  *
  * @see LabelProvider
  */
diff --git a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/logmanager/DefaultConsoleHandler.java b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/logmanager/DefaultConsoleHandler.java
index 475a15d..61d2961 100644
--- a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/logmanager/DefaultConsoleHandler.java
+++ b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/logmanager/DefaultConsoleHandler.java
@@ -18,9 +18,9 @@ import org.jboss.logmanager.handlers.ConsoleHandler;
  * java.util.logging.LogManager#readConfiguration(InputStream)}), you can use this handler by
  * setting the following properties:
  *
- * <pre>{@code
+ * {@snippet lang="properties" :
  * handlers = eu.mulk.quarkus.googlecloud.jsonlogging.logmanager.ConsoleHandler
- * }</pre>
+ * }
  *
  * <p><strong>Note:</strong> You can use {@code org.slf4j.bridge.SLF4JBridgeHandler} from {@code
  * org.slf4j:jul-to-slf4j} instead if you also have {@code org.jboss.slf4j:slf4j-jboss-logmanager}
@@ -36,15 +36,15 @@ import org.jboss.logmanager.handlers.ConsoleHandler;
  * below), you need to accompany this with an entry in {@code application.properties} that points to
  * your {@code logging.properties} file:
  *
- * <pre>{@code
+ * {@snippet lang="properties" :
  * logging.config = classpath:logging.properties
- * }</pre>
+ * }
  *
  * <p>In order to ensure that Spring Boot chooses {@code JavaLoggingSystem} over other
  * implementations, make sure that no other logging backends are present on the class path. A simple
  * way of doing this is by relying on {@code spring-boot-starter-logging} while excluding Logback:
  *
- * <pre>{@code
+ * {@snippet lang="xml" :
  * <dependency>
  *   <groupId>org.springframework.boot</groupId>
  *   <artifactId>spring-boot-starter</artifactId>
@@ -55,7 +55,7 @@ import org.jboss.logmanager.handlers.ConsoleHandler;
  *     </exclusion>
  *   </exclusions>
  * </dependency>
- * }</pre>
+ * }
  *
  * <p>You will probably want to include at least {@code org.jboss.slf4j:slf4j-jboss-logmanager} as
  * well. In addition, {@code org.slf4j:jcl-over-slf4j}, {@code
diff --git a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/package-info.java b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/package-info.java
index 8f8e495..93cf21e 100644
--- a/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/package-info.java
+++ b/core/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/package-info.java
@@ -33,7 +33,7 @@
  *
  * <h3 id="sect-installation-maven">Installation with Maven</h3>
  *
- * <pre>{@code
+ * {@snippet lang="xml" :
  * <project>
  *   ...
  *
@@ -51,19 +51,19 @@
  *
  *   ...
  * </project>
- * }</pre>
+ * }
  *
  * <h3 id="sect-installation-gradle">Installation with Gradle</h3>
  *
- * <pre>{@code
+ * {@snippet lang="groovy" :
  * dependencies {
- *   ...
+ *   // ...
  *
  *   implementation("eu.mulk.quarkus-googlecloud-jsonlogging:quarkus-googlecloud-jsonlogging-core:4.0.0")
  *
- *   ...
+ *   // ...
+ * }
  * }
- * }</pre>
  *
  * <h2 id="sect-usage">Usage</h2>
  *
@@ -94,18 +94,18 @@
  *
  * <p><strong>Example:</strong>
  *
- * <pre>{@code
+ * {@snippet :
  * logger.logf(
  *   "Request rejected: unauthorized.",
  *   Label.of("requestId", "123"),
  *   KeyValueParameter.of("resource", "/users/mulk"),
  *   KeyValueParameter.of("method", "PATCH"),
  *   KeyValueParameter.of("reason", "invalid token"));
- * }</pre>
+ * }
  *
- * Result:
+ * <p>Result:
  *
- * <pre>{@code
+ * {@snippet lang="json" :
  * {
  *   "jsonPayload": {
  *     "message": "Request rejected: unauthorized.",
@@ -117,7 +117,7 @@
  *     "requestId": "123"
  *   }
  * }
- * }</pre>
+ * }
  *
  * <h3 id="sect-usage-provider">Using LabelProvider and StructuredParameterProvider</h3>
  *
@@ -138,7 +138,7 @@
  *
  * <p><strong>Example:</strong>
  *
- * <pre>{@code
+ * {@snippet :
  * @Singleton
  * @Unremovable
  * public final class TraceLogParameterProvider implements StructuredParameterProvider, LabelProvider {
@@ -156,11 +156,11 @@
  *     return List.of(Label.of("requestId", "123"));
  *   }
  * }
- * }</pre>
+ * }
  *
  * Result:
  *
- * <pre>{@code
+ * {@snippet lang="json" :
  * {
  *   "jsonPayload": {
  *     "message": "Request rejected: unauthorized.",
@@ -171,7 +171,7 @@
  *     "requestId": "123"
  *   }
  * }
- * }</pre>
+ * }
  *
  * <h3 id="sect-usage-mdc">Using the Mapped Diagnostic Context</h3>
  *
@@ -180,15 +180,15 @@
  *
  * <p><strong>Example:</strong>
  *
- * <pre>{@code
+ * {@snippet :
  * MDC.put("resource", "/users/mulk");
  * MDC.put("method", "PATCH");
  * logger.logf("Request rejected: unauthorized.");
- * }</pre>
+ * }
  *
  * Result:
  *
- * <pre>{@code
+ * {@snippet lang="json" :
  * {
  *   "jsonPayload": {
  *     "message": "Request rejected: unauthorized.",
@@ -196,6 +196,6 @@
  *     "method": "PATCH"
  *   }
  * }
- * }</pre>
+ * }
  */
 package eu.mulk.quarkus.googlecloud.jsonlogging;
diff --git a/pom.xml b/pom.xml
index 16cf858..e5cb74f 100644
--- a/pom.xml
+++ b/pom.xml
@@ -62,6 +62,7 @@ SPDX-License-Identifier: LGPL-3.0-or-later
 
     <compiler-plugin.version>3.8.1</compiler-plugin.version>
     <failsafe-plugin.version>${surefire-plugin.version}</failsafe-plugin.version>
+    <flatten-plugin.version>1.2.7</flatten-plugin.version>
     <google-java-format.version>1.13.0</google-java-format.version>
     <jar-plugin.version>3.2.2</jar-plugin.version>
     <maven-gpg-plugin.version>1.5</maven-gpg-plugin.version>
@@ -139,6 +140,27 @@ SPDX-License-Identifier: LGPL-3.0-or-later
           <version>${jar-plugin.version}</version>
         </plugin>
 
+        <plugin>
+          <groupId>org.codehaus.mojo</groupId>
+          <artifactId>flatten-maven-plugin</artifactId>
+          <version>${flatten-plugin.version}</version>
+          <executions>
+            <execution>
+              <id>flatten</id>
+              <phase>process-resources</phase>
+              <goals>
+                <goal>flatten</goal>
+              </goals>
+            </execution>
+            <execution>
+              <id>flatten.clean</id>
+              <phase>clean</phase>
+              <goals>
+                <goal>clean</goal>
+              </goals>
+            </execution>
+          </executions>
+        </plugin>
       </plugins>
 
     </pluginManagement>
@@ -175,6 +197,18 @@ SPDX-License-Identifier: LGPL-3.0-or-later
         </configuration>
       </plugin>
 
+      <plugin>
+        <groupId>org.codehaus.mojo</groupId>
+        <artifactId>flatten-maven-plugin</artifactId>
+        <configuration>
+          <flattenMode>oss</flattenMode>
+          <flattenDependencyMode>all</flattenDependencyMode>
+          <pomElements>
+            <distributionManagement>flatten</distributionManagement>
+          </pomElements>
+        </configuration>
+      </plugin>
+
     </plugins>
   </build>
 
diff --git a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/runtime/package-info.java b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/runtime/package-info.java
index 3d1af08..657806f 100644
--- a/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/runtime/package-info.java
+++ b/runtime/src/main/java/eu/mulk/quarkus/googlecloud/jsonlogging/runtime/package-info.java
@@ -33,7 +33,7 @@
  *
  * <h3 id="sect-activation-maven">Activation with Maven</h3>
  *
- * <pre>{@code
+ * {@snippet lang="xml" :
  * <project>
  *   ...
  *
@@ -51,19 +51,19 @@
  *
  *   ...
  * </project>
- * }</pre>
+ * }
  *
  * <h3 id="sect-activation-gradle">Activation with Gradle</h3>
  *
- * <pre>{@code
+ * {@snippet lang="groovy" :
  * dependencies {
- *   ...
+ *   // ...
  *
  *   implementation("eu.mulk.quarkus-googlecloud-jsonlogging:quarkus-googlecloud-jsonlogging:4.0.0")
  *
- *   ...
+ *   // ...
+ * }
  * }
- * }</pre>
  *
  * <h2 id="sect-usage">Usage</h2>
  *