Fix minor typos and warnings

apache · Feb 8, 2024 · 975a312 · 975a312
1 parent 6cda1cb
commit 975a312
Show file tree

Hide file tree

Showing 5 changed files with 67 additions and 14 deletions.
diff --git a/log4j-docgen/pom.xml b/log4j-docgen/pom.xml
@@ -80,6 +80,52 @@
   <build>
     <plugins>
 
+      <!--
+        ~ We split compilation in two executions, so we can fail on warnings for our sources,
+        ~ but be more tolerant for generated sources.
+        -->
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>default-compile</id>
+            <phase>none</phase>
+          </execution>
+          <execution>
+            <id>compile-modello-sources</id>
+            <goals>
+              <goal>compile</goal>
+            </goals>
+            <configuration>
+              <!-- Modello-generated classes -->
+              <includes>
+                <include>org/apache/logging/log4j/docgen/*.java</include>
+                <include>org/apache/logging/log4j/docgen/freemarker/*.java</include>
+                <include>org/apache/logging/log4j/docgen/io/stax/*.java</include>
+                <include>org/apache/logging/log4j/docgen/xsd/*.java</include>
+              </includes>
+            </configuration>
+          </execution>
+          <execution>
+            <id>compile-main</id>
+            <goals>
+              <goal>compile</goal>
+            </goals>
+            <configuration>
+              <!-- Modello-generated classes -->
+              <excludes>
+                <exclude>org/apache/logging/log4j/docgen/*.java</exclude>
+                <exclude>org/apache/logging/log4j/docgen/freemarker/*.java</exclude>
+                <exclude>org/apache/logging/log4j/docgen/io/stax/*.java</exclude>
+                <exclude>org/apache/logging/log4j/docgen/xsd/*.java</exclude>
+              </excludes>
+              <failOnWarning>true</failOnWarning>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+
       <plugin>
         <groupId>org.codehaus.modello</groupId>
         <artifactId>modello-maven-plugin</artifactId>

diff --git a/...en/src/main/java/org/apache/logging/log4j/docgen/internal/DefaultFreeMarkerGenerator.java b/...en/src/main/java/org/apache/logging/log4j/docgen/internal/DefaultFreeMarkerGenerator.java
@@ -52,11 +52,12 @@ public class DefaultFreeMarkerGenerator implements FreeMarkerGenerator {
 
     private static final String CHARSET = "UTF-8";
 
+    @Override
     public void generateDocumentation(final FreeMarkerGeneratorRequest request) throws IOException {
         final PluginSet configurationSet;
         try {
             configurationSet = new PluginBundleStaxReader().read(getClass().getResourceAsStream("configuration.xml"));
-        } catch (XMLStreamException e) {
+        } catch (final XMLStreamException e) {
             throw new RuntimeException("Internal error: unable to parse resource `configuration.xml`.", e);
         }
         final Collection<PluginSet> extendedSets = new ArrayList<>(request.getPluginSets());

diff --git a/log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/util/TypeLookup.java b/log4j-docgen/src/main/java/org/apache/logging/log4j/docgen/util/TypeLookup.java
@@ -16,6 +16,7 @@
  */
 package org.apache.logging.log4j.docgen.util;
 
+import java.io.Serial;
 import java.util.HashSet;
 import java.util.Set;
 import java.util.TreeMap;
@@ -25,31 +26,31 @@
 import org.apache.logging.log4j.docgen.PluginType;
 import org.apache.logging.log4j.docgen.Type;
 
-public class TypeLookup extends TreeMap<String, Type> {
+public final class TypeLookup extends TreeMap<String, Type> {
 
-    private static final Predicate<PluginType> HAS_CORE_NAMESPACE = p -> "Core".equals(p.getNamespace());
+    @Serial
+    private static final long serialVersionUID = 1L;
 
-    public static TypeLookup of(final Iterable<PluginSet> sets) {
+    public static TypeLookup of(final Iterable<? extends PluginSet> sets) {
         return new TypeLookup(sets);
     }
 
-    private TypeLookup(final Iterable<PluginSet> sets) {
+    private TypeLookup(final Iterable<? extends PluginSet> sets) {
+        final Predicate<PluginType> hasCoreNamespace = p -> "Core".equals(p.getNamespace());
         // Round 1: Merge all the information from the sets
         sets.forEach(set -> {
             set.getScalars().forEach(scalar -> put(scalar.getClassName(), scalar));
             set.getAbstractTypes().forEach(abstractType -> put(abstractType.getClassName(), abstractType));
-            set.getPlugins().stream().filter(HAS_CORE_NAMESPACE).forEach(plugin -> put(plugin.getClassName(), plugin));
+            set.getPlugins().stream().filter(hasCoreNamespace).forEach(plugin -> put(plugin.getClassName(), plugin));
         });
         // Round 2: fill in the set of abstract types used in elements and the list of their possible implementations
         final Set<String> requiredAbstractTypes = new HashSet<>();
-        sets.forEach(set -> {
-            set.getPlugins().stream().filter(HAS_CORE_NAMESPACE).forEach(plugin -> {
-                plugin.getSupertypes().forEach(supertype -> ((AbstractType)
-                                computeIfAbsent(supertype, TypeLookup::createAbstractType))
-                        .addImplementation(plugin.getClassName()));
-                plugin.getElements().forEach(element -> requiredAbstractTypes.add(element.getType()));
-            });
-        });
+        sets.forEach(set -> set.getPlugins().stream().filter(hasCoreNamespace).forEach(plugin -> {
+            plugin.getSupertypes()
+                    .forEach(supertype -> ((AbstractType) computeIfAbsent(supertype, TypeLookup::createAbstractType))
+                            .addImplementation(plugin.getClassName()));
+            plugin.getElements().forEach(element -> requiredAbstractTypes.add(element.getType()));
+        }));
         // Round 3: remove the types that are not required and do not have a description
         values().removeIf(
                         type -> !requiredAbstractTypes.contains(type.getClassName()) && type.getDescription() == null);

diff --git a/log4j-docgen/src/test/resources/expected/freemarker/scalars.adoc b/log4j-docgen/src/test/resources/expected/freemarker/scalars.adoc
@@ -29,6 +29,7 @@ boolean
 a|A boolean value.
 
 Possible values:
+
 * `false`: false
 * `true`: true
 |[[byte]]
@@ -55,6 +56,7 @@ a|Represents a logging level.
 **Note**: the Log4j API supports custom levels, the following list contains only the standard ones.
 
 Possible values:
+
 * `OFF`: Special level that disables logging. No events should be logged at this level.
 * `FATAL`: A fatal event that will prevent the application from continuing.
 * `ERROR`: An error in the application, possibly recoverable.
@@ -68,6 +70,7 @@ o.a.l.l.core.Filter.Result
 a|The result that can returned from a filter method call.
 
 Possible values:
+
 * `ACCEPT`: The event will be processed without further filtering based on the log Level.
 * `NEUTRAL`: No decision could be made, further filtering should occur.
 * `DENY`: The event should not be processed.
@@ -76,6 +79,7 @@ o.a.l.l.core.appender.ConsoleAppender.Target
 a|Specifies the target of a console appender.
 
 Possible values:
+
 * `SYSTEM_OUT`: Logs to the standard output.
 * `SYSTEM_ERR`: Logs to the standard error.
 |[[short]]

diff --git a/log4j-docgen/src/test/resources/templates/scalars.ftl b/log4j-docgen/src/test/resources/templates/scalars.ftl
@@ -34,6 +34,7 @@ a|${scalar.description.text}
     <#if scalar.values?size != 0>
 
 Possible values:
+
         <#list scalar.values as value>
 * `${value.name}`: ${value.description.text}
         </#list>