From 3b8de119174d80547518dc9a021a0fe82ff09f22 Mon Sep 17 00:00:00 2001
From: Grzegorz Piwowarek <gpiwowarek@gmail.com>
Date: Thu, 17 Oct 2024 07:27:51 +0200
Subject: [PATCH] Add GitHub Actions job for JavaDoc verification

---
 .github/workflows/build.yml                   | 16 +++++
 pom.xml                                       | 37 +++++++++--
 .../collectors/ParallelCollectors.java        | 65 ++++++++++---------
 src/main/java/module-info.java                |  3 +
 4 files changed, 83 insertions(+), 38 deletions(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index a8c84f8c..103661b3 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -31,3 +31,19 @@ jobs:
       - name: Build with Maven
         run: mvn package
 
+  verify-javadoc:
+    runs-on: ubuntu-latest
+    name: Validate JavaDocs
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup JDK
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '23'
+          architecture: 'x64'
+          cache: 'maven'
+
+      - name: Validate JavaDocs
+        run: mvn -Pdoclint package -DskipTests=true
+
diff --git a/pom.xml b/pom.xml
index a37e5fc3..8fa7d9b8 100644
--- a/pom.xml
+++ b/pom.xml
@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 
     <licenses>
         <license>
@@ -25,11 +26,12 @@
         <url>https://github.com/pivovarit/parallel-collectors</url>
         <connection>scm:git:git@github.com:pivovarit/parallel-collectors.git</connection>
         <developerConnection>scm:git:git@github.com:pivovarit/parallel-collectors.git</developerConnection>
-      <tag>HEAD</tag>
-  </scm>
+        <tag>HEAD</tag>
+    </scm>
 
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <maven.javadoc.plugin.version>3.10.1</maven.javadoc.plugin.version>
         <junit.version>5.11.2</junit.version>
         <assertj.version>3.26.3</assertj.version>
         <awaitility.version>4.2.2</awaitility.version>
@@ -47,8 +49,7 @@
                 <artifactId>maven-compiler-plugin</artifactId>
                 <version>3.13.0</version>
                 <configuration>
-                    <source>21</source>
-                    <target>21</target>
+                    <release>21</release>
                 </configuration>
             </plugin>
 
@@ -126,7 +127,7 @@
                     <plugin>
                         <groupId>org.apache.maven.plugins</groupId>
                         <artifactId>maven-javadoc-plugin</artifactId>
-                        <version>3.10.1</version>
+                        <version>${maven.javadoc.plugin.version}</version>
                         <executions>
                             <execution>
                                 <id>attach-javadocs</id>
@@ -247,6 +248,30 @@
                 </plugins>
             </build>
         </profile>
+        <profile>
+            <id>doclint</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-javadoc-plugin</artifactId>
+                        <version>${maven.javadoc.plugin.version}</version>
+                        <executions>
+                            <execution>
+                                <id>attach-javadocs</id>
+                                <goals>
+                                    <goal>jar</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                        <configuration>
+                            <failOnWarnings>true</failOnWarnings>
+                            <failOnError>true</failOnError>
+                        </configuration>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
     </profiles>
 
     <dependencies>
diff --git a/src/main/java/com/pivovarit/collectors/ParallelCollectors.java b/src/main/java/com/pivovarit/collectors/ParallelCollectors.java
index 0ea272bd..3a16bdfc 100644
--- a/src/main/java/com/pivovarit/collectors/ParallelCollectors.java
+++ b/src/main/java/com/pivovarit/collectors/ParallelCollectors.java
@@ -28,11 +28,11 @@ private ParallelCollectors() {
      *   .collect(parallel(i -> foo(i), toList()));
      * }</pre>
      *
-     * @param mapper      a transformation to be performed in parallel
-     * @param collector   the {@code Collector} describing the reduction
-     * @param <T>         the type of the collected elements
-     * @param <R>         the result returned by {@code mapper}
-     * @param <RR>        the reduction result {@code collector}
+     * @param mapper    a transformation to be performed in parallel
+     * @param collector the {@code Collector} describing the reduction
+     * @param <T>       the type of the collected elements
+     * @param <R>       the result returned by {@code mapper}
+     * @param <RR>      the reduction result {@code collector}
      *
      * @return a {@code Collector} which collects all processed elements into a user-provided mutable {@code Collection} in parallel
      *
@@ -106,12 +106,12 @@ private ParallelCollectors() {
      *   .collect(parallel(i -> foo(i), toList(), executor));
      * }</pre>
      *
-     * @param mapper      a transformation to be performed in parallel
-     * @param collector   the {@code Collector} describing the reduction
-     * @param executor    the {@code Executor} to use for asynchronous execution
-     * @param <T>         the type of the collected elements
-     * @param <R>         the result returned by {@code mapper}
-     * @param <RR>        the reduction result {@code collector}
+     * @param mapper    a transformation to be performed in parallel
+     * @param collector the {@code Collector} describing the reduction
+     * @param executor  the {@code Executor} to use for asynchronous execution
+     * @param <T>       the type of the collected elements
+     * @param <R>       the result returned by {@code mapper}
+     * @param <RR>      the reduction result {@code collector}
      *
      * @return a {@code Collector} which collects all processed elements into a user-provided mutable {@code Collection} in parallel
      *
@@ -135,9 +135,9 @@ private ParallelCollectors() {
      *   .collect(parallel(i -> foo()));
      * }</pre>
      *
-     * @param mapper      a transformation to be performed in parallel
-     * @param <T>         the type of the collected elements
-     * @param <R>         the result returned by {@code mapper}
+     * @param mapper a transformation to be performed in parallel
+     * @param <T>    the type of the collected elements
+     * @param <R>    the result returned by {@code mapper}
      *
      * @return a {@code Collector} which collects all processed elements into a {@code Stream} in parallel
      *
@@ -162,6 +162,7 @@ private ParallelCollectors() {
      * }</pre>
      *
      * @param mapper      a transformation to be performed in parallel
+     * @param parallelism the max parallelism level
      * @param <T>         the type of the collected elements
      * @param <R>         the result returned by {@code mapper}
      *
@@ -215,10 +216,10 @@ private ParallelCollectors() {
      *   .collect(parallel(i -> foo(), executor));
      * }</pre>
      *
-     * @param mapper      a transformation to be performed in parallel
-     * @param executor    the {@code Executor} to use for asynchronous execution
-     * @param <T>         the type of the collected elements
-     * @param <R>         the result returned by {@code mapper}
+     * @param mapper   a transformation to be performed in parallel
+     * @param executor the {@code Executor} to use for asynchronous execution
+     * @param <T>      the type of the collected elements
+     * @param <R>      the result returned by {@code mapper}
      *
      * @return a {@code Collector} which collects all processed elements into a {@code Stream} in parallel
      *
@@ -242,9 +243,9 @@ private ParallelCollectors() {
      *   .forEach(System.out::println);
      * }</pre>
      *
-     * @param mapper      a transformation to be performed in parallel
-     * @param <T>         the type of the collected elements
-     * @param <R>         the result returned by {@code mapper}
+     * @param mapper a transformation to be performed in parallel
+     * @param <T>    the type of the collected elements
+     * @param <R>    the result returned by {@code mapper}
      *
      * @return a {@code Collector} which collects all processed elements into a {@code Stream} in parallel
      *
@@ -295,10 +296,10 @@ private ParallelCollectors() {
      *   .forEach(System.out::println);
      * }</pre>
      *
-     * @param mapper      a transformation to be performed in parallel
-     * @param executor    the {@code Executor} to use for asynchronous execution
-     * @param <T>         the type of the collected elements
-     * @param <R>         the result returned by {@code mapper}
+     * @param mapper   a transformation to be performed in parallel
+     * @param executor the {@code Executor} to use for asynchronous execution
+     * @param <T>      the type of the collected elements
+     * @param <R>      the result returned by {@code mapper}
      *
      * @return a {@code Collector} which collects all processed elements into a {@code Stream} in parallel
      *
@@ -350,9 +351,9 @@ private ParallelCollectors() {
      *   .forEach(System.out::println);
      * }</pre>
      *
-     * @param mapper      a transformation to be performed in parallel
-     * @param <T>         the type of the collected elements
-     * @param <R>         the result returned by {@code mapper}
+     * @param mapper a transformation to be performed in parallel
+     * @param <T>    the type of the collected elements
+     * @param <R>    the result returned by {@code mapper}
      *
      * @return a {@code Collector} which collects all processed elements into a {@code Stream} in parallel
      *
@@ -403,10 +404,10 @@ private ParallelCollectors() {
      *   .forEach(System.out::println);
      * }</pre>
      *
-     * @param mapper      a transformation to be performed in parallel
-     * @param executor    the {@code Executor} to use for asynchronous execution
-     * @param <T>         the type of the collected elements
-     * @param <R>         the result returned by {@code mapper}
+     * @param mapper   a transformation to be performed in parallel
+     * @param executor the {@code Executor} to use for asynchronous execution
+     * @param <T>      the type of the collected elements
+     * @param <R>      the result returned by {@code mapper}
      *
      * @return a {@code Collector} which collects all processed elements into a {@code Stream} in parallel
      *
diff --git a/src/main/java/module-info.java b/src/main/java/module-info.java
index 3ed46d4e..6c5663d4 100644
--- a/src/main/java/module-info.java
+++ b/src/main/java/module-info.java
@@ -1,3 +1,6 @@
+/**
+ * Parallel Collectors is a toolkit that eases parallel collection processing in Java using Stream API without the limitations imposed by standard Parallel Streams
+ */
 module parallel.collectors {
     exports com.pivovarit.collectors;
 }