Improve JavaDocs to reduce warnings during CI & release (#748)

asciidoctor-maven-commons/src/main/java/org/asciidoctor/maven/commons/StringUtils.java

@@ -7,6 +7,15 @@
  */
 public class StringUtils {
 
+    private StringUtils() {
+    }
+
+    /**
+     * Whether a {@link CharSequence} it blank (null, empty or white characters).
+     *
+     * @param cs character sequence
+     * @return {@literal true} if input is blank
+     */
     public static boolean isBlank(final CharSequence cs) {
         int strLen;
         if (cs != null && (strLen = cs.length()) != 0) {
@@ -19,6 +28,12 @@ public static boolean isBlank(final CharSequence cs) {
         return true;
     }
 
+    /**
+     * Whether a {@link CharSequence} it not blank (null, empty or white characters).
+     *
+     * @param cs character sequence
+     * @return {@literal true} if input is not blank
+     */
     public static boolean isNotBlank(final CharSequence cs) {
         return !isBlank(cs);
     }

asciidoctor-maven-plugin/src/main/java/org/asciidoctor/maven/extensions/AsciidoctorJExtensionRegistry.java

@@ -1,7 +1,16 @@
 package org.asciidoctor.maven.extensions;
 
 import org.asciidoctor.Asciidoctor;
-import org.asciidoctor.extension.*;
+import org.asciidoctor.extension.BlockMacroProcessor;
+import org.asciidoctor.extension.BlockProcessor;
+import org.asciidoctor.extension.DocinfoProcessor;
+import org.asciidoctor.extension.IncludeProcessor;
+import org.asciidoctor.extension.InlineMacroProcessor;
+import org.asciidoctor.extension.JavaExtensionRegistry;
+import org.asciidoctor.extension.Postprocessor;
+import org.asciidoctor.extension.Preprocessor;
+import org.asciidoctor.extension.Processor;
+import org.asciidoctor.extension.Treeprocessor;
 
 /**
  * Class responsible for registering extensions.
@@ -12,6 +21,11 @@ public class AsciidoctorJExtensionRegistry implements ExtensionRegistry {
 
     private JavaExtensionRegistry javaExtensionRegistry;
 
+    /**
+     * Constructor.
+     *
+     * @param asciidoctorInstance Asciidoctor instance
+     */
     public AsciidoctorJExtensionRegistry(Asciidoctor asciidoctorInstance) {
         javaExtensionRegistry = asciidoctorInstance.javaExtensionRegistry();
     }

asciidoctor-maven-plugin/src/main/java/org/asciidoctor/maven/http/AsciidoctorHandler.java

@@ -5,7 +5,13 @@
 import io.netty.channel.ChannelFutureListener;
 import io.netty.channel.ChannelHandlerContext;
 import io.netty.channel.SimpleChannelInboundHandler;
-import io.netty.handler.codec.http.*;
+import io.netty.handler.codec.http.DefaultFullHttpResponse;
+import io.netty.handler.codec.http.FullHttpRequest;
+import io.netty.handler.codec.http.HttpHeaderNames;
+import io.netty.handler.codec.http.HttpHeaders;
+import io.netty.handler.codec.http.HttpMethod;
+import io.netty.handler.codec.http.HttpResponseStatus;
+import io.netty.handler.codec.http.HttpVersion;
 import io.netty.util.CharsetUtil;
 import org.apache.commons.io.FileUtils;
 import org.apache.commons.io.IOUtils;

asciidoctor-maven-plugin/src/main/java/org/asciidoctor/maven/http/AsciidoctorHttpServer.java

@@ -18,6 +18,9 @@
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.atomic.AtomicInteger;
 
+/**
+ * HTTP server to expose AsciiDoc converted sources.
+ */
 public class AsciidoctorHttpServer {
 
     private static final String HOST = "localhost";
@@ -32,13 +35,26 @@ public class AsciidoctorHttpServer {
     private ServerBootstrap bootstrap;
     private NioEventLoopGroup workerGroup;
 
-    public AsciidoctorHttpServer(final Log logger, final int port, final File outputDirectory, final String defaultPage) {
+    /**
+     * Constructor.
+     *
+     * @param logger           server logger
+     * @param port             server port
+     * @param workingDirectory sources location
+     * @param defaultPage      default page used for root (aka. index)
+     */
+    public AsciidoctorHttpServer(final Log logger, final int port, final File workingDirectory, final String defaultPage) {
         this.logger = logger;
         this.port = port;
-        this.workDir = outputDirectory;
+        this.workDir = workingDirectory;
         this.defaultPage = defaultPage;
     }
 
+    /**
+     * Start server.
+     *
+     * @return server instance
+     */
     public AsciidoctorHttpServer start() {
         final AtomicInteger threadId = new AtomicInteger(1);
         workerGroup = new NioEventLoopGroup(THREAD_NUMBER, runnable -> {
@@ -85,6 +101,9 @@ protected void initChannel(final SocketChannel ch) {
         return this;
     }
 
+    /**
+     * Stop server.
+     */
     public void stop() {
         Future<?> shutdownGracefully = workerGroup.shutdownGracefully();
         logger.info("Server stopping...");

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/AsciidoctorAstDoxiaParser.java

@@ -5,7 +5,12 @@
 import org.apache.maven.doxia.parser.Parser;
 import org.apache.maven.doxia.sink.Sink;
 import org.apache.maven.project.MavenProject;
-import org.asciidoctor.*;
+import org.asciidoctor.Asciidoctor;
+import org.asciidoctor.Attributes;
+import org.asciidoctor.AttributesBuilder;
+import org.asciidoctor.Options;
+import org.asciidoctor.OptionsBuilder;
+import org.asciidoctor.SafeMode;
 import org.asciidoctor.ast.Document;
 import org.asciidoctor.maven.log.LogHandler;
 import org.asciidoctor.maven.log.LogRecordFormatter;
@@ -33,6 +38,7 @@
  * (see <a href="https://maven.apache.org/plugins/maven-site-plugin/">maven-site-plugin</a>).
  *
  * @author abelsromero
+ * @since 3.0.0
  */
 @Component(role = Parser.class, hint = AsciidoctorAstDoxiaParser.ROLE_HINT)
 public class AsciidoctorAstDoxiaParser extends AbstractTextParser {

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/AsciidoctorAstDoxiaParserModule.java

@@ -11,6 +11,7 @@
  * <a href="https://maven.apache.org/doxia/references/">Doxia provided modules</a>.
  *
  * @author abelsromero
+ * @since 3.0.0
  */
 @Component(role = ParserModule.class, hint = AsciidoctorAstDoxiaParser.ROLE_HINT)
 public class AsciidoctorAstDoxiaParserModule extends AbstractParserModule {

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/NodeProcessor.java

@@ -10,20 +10,23 @@
  * a specific Node type (but can be accommodated to convert multiples).
  *
  * @author abelsromero
+ * @since 3.0.0
  */
 public interface NodeProcessor {
 
     /**
      * Whether the processor can process the node.
      *
      * @param node candidate node to process
+     * @return {@literal true} if the node can be processed
      */
     boolean applies(StructuralNode node);
 
     /**
      * Whether sub-nodes should be processed recursively.
      *
      * @param node candidate node to process
+     * @return {@literal true} if the node is terminal
      */
     default boolean isTerminal(StructuralNode node) {
         return false;

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/NodesSinker.java

@@ -1,24 +1,40 @@
 package org.asciidoctor.maven.site.ast;
 
-import org.apache.maven.doxia.sink.Sink;
-import org.asciidoctor.ast.StructuralNode;
-import org.asciidoctor.maven.site.ast.processors.*;
-
 import java.util.Arrays;
 import java.util.List;
 import java.util.Optional;
 
+import org.apache.maven.doxia.sink.Sink;
+import org.asciidoctor.ast.StructuralNode;
+import org.asciidoctor.maven.site.ast.processors.DocumentNodeProcessor;
+import org.asciidoctor.maven.site.ast.processors.ImageNodeProcessor;
+import org.asciidoctor.maven.site.ast.processors.ListItemNodeProcessor;
+import org.asciidoctor.maven.site.ast.processors.ListingNodeProcessor;
+import org.asciidoctor.maven.site.ast.processors.LiteralNodeProcessor;
+import org.asciidoctor.maven.site.ast.processors.OrderedListNodeProcessor;
+import org.asciidoctor.maven.site.ast.processors.ParagraphNodeProcessor;
+import org.asciidoctor.maven.site.ast.processors.PreambleNodeProcessor;
+import org.asciidoctor.maven.site.ast.processors.SectionNodeProcessor;
+import org.asciidoctor.maven.site.ast.processors.TableNodeProcessor;
+import org.asciidoctor.maven.site.ast.processors.UnorderedListNodeProcessor;
+
 /**
  * Document processor.
  * Responsible for initializing the different Node Processors
  * and traverse the AST.
  *
  * @author abelsromero
+ * @since 3.0.0
  */
 public class NodesSinker {
 
     private final List<NodeProcessor> nodeProcessors;
 
+    /**
+     * Constructor.
+     *
+     * @param sink Doxia {@link Sink}
+     */
     public NodesSinker(Sink sink) {
 
         UnorderedListNodeProcessor unorderedListNodeProcessor = new UnorderedListNodeProcessor(sink);
@@ -43,6 +59,11 @@ public NodesSinker(Sink sink) {
         );
     }
 
+    /**
+     * Processes an Asciidoctor AST node.
+     *
+     * @param node Asciidoctor {@link StructuralNode}
+     */
     public void processNode(StructuralNode node) {
         processNode(node, 0);
     }

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/processors/AbstractSinkNodeProcessor.java

@@ -3,14 +3,30 @@
 import org.apache.maven.doxia.sink.Sink;
 import org.asciidoctor.ast.ContentNode;
 
+/**
+ * Recommended base case to build a {@link org.asciidoctor.maven.site.ast.NodeProcessor}.
+ *
+ * @author abelsromero
+ * @since 3.0.0
+ */
 public class AbstractSinkNodeProcessor {
 
     private final Sink sink;
 
+    /**
+     * Constructor.
+     *
+     * @param sink Doxia {@link Sink}
+     */
     public AbstractSinkNodeProcessor(Sink sink) {
         this.sink = sink;
     }
 
+    /**
+     * Returns internal {@link Sink}.
+     *
+     * @return Doxia {@link Sink}
+     */
     protected Sink getSink() {
         return sink;
     }

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/processors/DocumentNodeProcessor.java

@@ -4,8 +4,19 @@
 import org.asciidoctor.ast.StructuralNode;
 import org.asciidoctor.maven.site.ast.NodeProcessor;
 
+/**
+ * Root document processor.
+ *
+ * @author abelsromero
+ * @since 3.0.0
+ */
 public class DocumentNodeProcessor extends AbstractSinkNodeProcessor implements NodeProcessor {
 
+    /**
+     * Constructor.
+     *
+     * @param sink Doxia {@link Sink}
+     */
     public DocumentNodeProcessor(Sink sink) {
         super(sink);
     }

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/processors/ImageNodeProcessor.java

@@ -10,9 +10,17 @@
 
 /**
  * Inline images are processed as paragraphs.
+ *
+ * @author abelsromero
+ * @since 3.0.0
  */
 public class ImageNodeProcessor extends AbstractSinkNodeProcessor implements NodeProcessor {
 
+    /**
+     * Constructor.
+     *
+     * @param sink Doxia {@link Sink}
+     */
     public ImageNodeProcessor(Sink sink) {
         super(sink);
     }

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/processors/ListItemNodeProcessor.java

@@ -7,15 +7,31 @@
 
 import java.util.List;
 
+/**
+ * List items processor, including numbered and unnumbered.
+ *
+ * @author abelsromero
+ * @since 3.0.0
+ */
 public class ListItemNodeProcessor extends AbstractSinkNodeProcessor implements NodeProcessor {
 
     private List<NodeProcessor> nodeProcessors;
 
+    /**
+     * Constructor.
+     *
+     * @param sink Doxia {@link Sink}
+     */
     public ListItemNodeProcessor(Sink sink) {
         super(sink);
 
     }
 
+    /**
+     * Inject a list of {@link NodeProcessor}.
+     *
+     * @param nodeProcessors {@link List} of {@link NodeProcessor}
+     */
     public void setNodeProcessors(List<NodeProcessor> nodeProcessors) {
         this.nodeProcessors = nodeProcessors;
     }

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/processors/ListingNodeProcessor.java

@@ -10,6 +10,9 @@
 /**
  * Processes code blocks.
  * Create a block compatible with maven-fluido-skin's use code-prettify.
+ *
+ * @author abelsromero
+ * @since 3.0.0
  */
 public class ListingNodeProcessor extends AbstractSinkNodeProcessor implements NodeProcessor {
 
@@ -19,6 +22,11 @@ public class ListingNodeProcessor extends AbstractSinkNodeProcessor implements N
 
     private final ListItemNodeProcessor itemNodeProcessor;
 
+    /**
+     * Constructor.
+     *
+     * @param sink Doxia {@link Sink}
+     */
     public ListingNodeProcessor(Sink sink) {
         super(sink);
         this.itemNodeProcessor = new ListItemNodeProcessor(sink);

asciidoctor-parser-doxia-module/src/main/java/org/asciidoctor/maven/site/ast/processors/LiteralNodeProcessor.java

@@ -5,10 +5,21 @@
 import org.asciidoctor.jruby.ast.impl.BlockImpl;
 import org.asciidoctor.maven.site.ast.NodeProcessor;
 
+/**
+ * Literal (aka. monospace) text processor.
+ *
+ * @author abelsromero
+ * @since 3.0.0
+ */
 public class LiteralNodeProcessor extends AbstractSinkNodeProcessor implements NodeProcessor {
 
     private final ListItemNodeProcessor itemNodeProcessor;
 
+    /**
+     * Constructor.
+     *
+     * @param sink Doxia {@link Sink}
+     */
     public LiteralNodeProcessor(Sink sink) {
         super(sink);
         this.itemNodeProcessor = new ListItemNodeProcessor(sink);