From 37ac4c90bb58fc53fa41f4339b610439cbfe0b50 Mon Sep 17 00:00:00 2001
From: Konrad Windszus <kwin@apache.org>
Date: Wed, 5 Apr 2023 20:32:48 +0200
Subject: [PATCH] Improve javadoc of "includes" and "excludes"

Use newest m-plugin-p 3.8.1
This closes #228
---
 build.xml                                      |  6 ++++--
 .../forbiddenapis/maven/AbstractCheckMojo.java | 18 ++++++++++++------
 src/main/maven/pom-build.xml.template          |  3 +++
 3 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/build.xml b/build.xml
index 81db0c20..d1b8b958 100644
--- a/build.xml
+++ b/build.xml
@@ -105,8 +105,8 @@
   <property file="build.properties" />
 
   <property name="jdk.version" value="1.7"/>
-  <property name="maven.version" value="2.2.1"/>
-  <property name="maven-plugin-plugin.version" value="3.4"/>
+  <property name="maven.version" value="3.2.5"/>
+  <property name="maven-plugin-plugin.version" value="3.8.1"/>
   
   <!-- with fork=false this somehow takes endless to download the internet, so let's fork - and slow down in an other way (startup) -->
   <property name="maven.fork" value="true"/>
@@ -672,6 +672,8 @@
         <exclude name="**/jdk-deprecated-*.txt"/>
         <exclude name="**/jdk-internal-*.txt"/>
         <exclude name="**/*.iml"/>
+        <exclude name="**/.project"/>
+        <exclude name="**/.settings"/>
       </fileset>
     </rat:report>
     <!-- now print the output, for review -->
diff --git a/src/main/java/de/thetaphi/forbiddenapis/maven/AbstractCheckMojo.java b/src/main/java/de/thetaphi/forbiddenapis/maven/AbstractCheckMojo.java
index de754d0f..61ba3734 100644
--- a/src/main/java/de/thetaphi/forbiddenapis/maven/AbstractCheckMojo.java
+++ b/src/main/java/de/thetaphi/forbiddenapis/maven/AbstractCheckMojo.java
@@ -35,6 +35,7 @@
 import de.thetaphi.forbiddenapis.ForbiddenApiException;
 import de.thetaphi.forbiddenapis.Logger;
 import de.thetaphi.forbiddenapis.ParseException;
+import de.thetaphi.forbiddenapis.maven.TestCheckMojo;
 
 import java.io.File;
 import java.io.IOException;
@@ -137,8 +138,8 @@ public abstract class AbstractCheckMojo extends AbstractMojo implements Constant
    * signatures that refer to methods or field in classes that are not on classpath,
    * e.g. This is useful in multi-module Maven builds where a common set of signatures is used,
    * that are not part of every sub-modules dependencies.
-   * @see #ignoreSignaturesOfMissingClasses)
-   * @deprecated The setting 'failOnUnresolvableSignatures' was deprecated and will be removed in next version. Use 'ignoreSignaturesOfMissingClasses' instead.
+   * @see #ignoreSignaturesOfMissingClasses
+   * @deprecated The setting {@code failOnUnresolvableSignatures} was deprecated and will be removed in next version. Use {@link #ignoreSignaturesOfMissingClasses} instead.
    * @since 1.4
    */
   @Deprecated
@@ -196,9 +197,11 @@ public abstract class AbstractCheckMojo extends AbstractMojo implements Constant
   private String releaseVersion;
 
   /**
-   * List of patterns matching all class files to be parsed from the classesDirectory.
-   * Can be changed to e.g. exclude several files (using excludes).
-   * The default is a single include with pattern '**&#47;*.class'
+   * List of <a href="https://ant.apache.org/manual/dirtasks.html#patterns">Ant patterns</a> which must match all relative class paths to be considered.
+   * All relative class paths matching one or more of the given patterns and not matching any of the ones from {@link #excludes} are considered.
+   * The given paths are relative to {@code classesDirectory}.
+   * Can be changed to e.g. exclude several files (using {@link #excludes}).
+   * The default is a single include with pattern {@code **&#47;*.class}.
    * @see #excludes
    * @since 1.0
    */
@@ -206,7 +209,10 @@ public abstract class AbstractCheckMojo extends AbstractMojo implements Constant
   private String[] includes;
 
   /**
-   * List of patterns matching class files to be excluded from checking.
+   * List of <a href="https://ant.apache.org/manual/dirtasks.html#patterns">Ant patterns</a>.
+   * All relative class paths matching one or more of the given patterns are skipped.
+   * The given paths are relative to {@code classesDirectory}.
+   *
    * @see #includes
    * @since 1.0
    */
diff --git a/src/main/maven/pom-build.xml.template b/src/main/maven/pom-build.xml.template
index 53340dc4..16f59bd2 100644
--- a/src/main/maven/pom-build.xml.template
+++ b/src/main/maven/pom-build.xml.template
@@ -43,6 +43,9 @@
             <extractor>java-javadoc</extractor>
             <extractor>java-annotations</extractor>
           </extractors>
+          <externalJavadocBaseUrls>
+            <externalJavadocBaseUrl>https://docs.oracle.com/javase/8/docs/api/</externalJavadocBaseUrl>
+          </externalJavadocBaseUrls>
         </configuration>
       </plugin>
       <plugin>