From 6a437c3f1bdc914fb96dc8cedced64272fcc73eb Mon Sep 17 00:00:00 2001
From: Valera V Harseko <vharseko@3a-systems.ru>
Date: Wed, 15 Jul 2026 21:14:39 +0300
Subject: [PATCH] Enforce Javadoc doclint via inherited property and
 failOnWarnings

Replace the blanket <doclint>none</doclint> with an inherited
<doclint>all,-missing</doclint> property (referenced as ${doclint}),
bump maven-javadoc-plugin to 3.12.0, and enable <failOnWarnings>true</failOnWarnings>
so Javadoc problems break the build.

Fix every doclint error and warning surfaced across modules on both
JDK 11 and JDK 26:
- ConditionalFilter: escape the <pre> code sample (nested-brace {@code} broke on JDK 11)
- GenericHeaplet: drop {@link} to non-existent GenericHeapObject
- RouterHandler, MCPServerFeaturesFilter: <br/> -> <br>
- MCPServerFeaturesFilter: escape bare & as &amp;
- ExpressionRequestAsyncFunction: add description for @param <V>
- OpenApiValidationFilter: remove orphan </p>
- Keys: drop type arguments from {@link Factory}
- JsonValues: <tt> -> <code>
- PasswordReplayFilterHeaplet: fix heading-level sequence (JDK 26)
---
 .../org/forgerock/http/filter/ConditionalFilter.java   |  7 +++----
 .../openig/ai/filter/MCPServerFeaturesFilter.java      |  4 ++--
 .../openig/el/ExpressionRequestAsyncFunction.java      |  3 ++-
 .../openig/filter/OpenApiValidationFilter.java         |  1 -
 .../openig/filter/PasswordReplayFilterHeaplet.java     |  7 ++++---
 .../forgerock/openig/handler/router/RouterHandler.java |  2 +-
 .../java/org/forgerock/openig/heap/GenericHeaplet.java |  3 ++-
 .../src/main/java/org/forgerock/openig/heap/Keys.java  |  3 ++-
 .../java/org/forgerock/openig/util/JsonValues.java     |  4 ++--
 pom.xml                                                | 10 +++++++---
 10 files changed, 25 insertions(+), 19 deletions(-)

diff --git a/contrib-http-framework/src/main/java/org/forgerock/http/filter/ConditionalFilter.java b/contrib-http-framework/src/main/java/org/forgerock/http/filter/ConditionalFilter.java
index 1c5554138..8146499ff 100644
--- a/contrib-http-framework/src/main/java/org/forgerock/http/filter/ConditionalFilter.java
+++ b/contrib-http-framework/src/main/java/org/forgerock/http/filter/ConditionalFilter.java
@@ -12,6 +12,7 @@
  * information: "Portions copyright [year] [name of copyright owner]".
  *
  * Copyright 2016 ForgeRock AS.
+ * Portions Copyrighted 2026 3A Systems, LLC.
  */
 
 package org.forgerock.http.filter;
@@ -48,18 +49,16 @@ public class ConditionalFilter implements Filter {
      * This constructor is provided as an ease to write some code : since you have access to the boolean,
      * you may optimise the code like this :
      * <pre>
-     *     {@code
      * if (condition) {
      *    return delegate;
      * } else {
      *    return new Filter() {
-     *       @Override
-     *       public Promise<Response, NeverThrowsException> filter(Context context, Request request, Handler handler) {
+     *       &#64;Override
+     *       public Promise&lt;Response, NeverThrowsException&gt; filter(Context context, Request request, Handler handler) {
      *          return handler.handle(context, request);
      *       }
      *    };
      * }
-     *     }
      * </pre>
      *
      * @param delegate
diff --git a/openig-ai/src/main/java/org/openidentityplatform/openig/ai/filter/MCPServerFeaturesFilter.java b/openig-ai/src/main/java/org/openidentityplatform/openig/ai/filter/MCPServerFeaturesFilter.java
index 5b53c7f53..f690cf661 100644
--- a/openig-ai/src/main/java/org/openidentityplatform/openig/ai/filter/MCPServerFeaturesFilter.java
+++ b/openig-ai/src/main/java/org/openidentityplatform/openig/ai/filter/MCPServerFeaturesFilter.java
@@ -46,8 +46,8 @@
 
 /**
  * MCPServerFeaturesFilter
- * <br/>
- * This filter enforces allow/deny policies for MCP (Management & Control Protocol)
+ * <br>
+ * This filter enforces allow/deny policies for MCP (Management &amp; Control Protocol)
  * features exchanged as JSON-RPC payloads with an MCP server. It inspects both
  * incoming requests and outgoing responses and removes or rejects features
  * according to the configured rules.
diff --git a/openig-core/src/main/java/org/forgerock/openig/el/ExpressionRequestAsyncFunction.java b/openig-core/src/main/java/org/forgerock/openig/el/ExpressionRequestAsyncFunction.java
index 98ec3d1c1..01f54fcec 100644
--- a/openig-core/src/main/java/org/forgerock/openig/el/ExpressionRequestAsyncFunction.java
+++ b/openig-core/src/main/java/org/forgerock/openig/el/ExpressionRequestAsyncFunction.java
@@ -12,6 +12,7 @@
  * information: "Portions copyright [year] [name of copyright owner]".
  *
  * Copyright 2016 ForgeRock AS.
+ * Portions Copyrighted 2026 3A Systems, LLC.
  */
 
 package org.forgerock.openig.el;
@@ -25,7 +26,7 @@
 
 /**
  * This is an implementation of the {@link AsyncFunction} based on the evaluation of an {@link Expression}.
- * @param <V>
+ * @param <V> the type of the value returned by the evaluated expression
  */
 public class ExpressionRequestAsyncFunction<V> implements AsyncFunction<ContextAndRequest, V, Exception> {
 
diff --git a/openig-core/src/main/java/org/forgerock/openig/filter/OpenApiValidationFilter.java b/openig-core/src/main/java/org/forgerock/openig/filter/OpenApiValidationFilter.java
index 953ec3528..8c3f16d59 100644
--- a/openig-core/src/main/java/org/forgerock/openig/filter/OpenApiValidationFilter.java
+++ b/openig-core/src/main/java/org/forgerock/openig/filter/OpenApiValidationFilter.java
@@ -64,7 +64,6 @@
  *       {@code 503 Service Unavailable}</li>
  *   <li>{@code false} (default) – log a warning and pass the original response through.</li>
  * </ul>
- * </p>
  *
  * <h2>Heap configuration</h2>
  * <pre>{@code
diff --git a/openig-core/src/main/java/org/forgerock/openig/filter/PasswordReplayFilterHeaplet.java b/openig-core/src/main/java/org/forgerock/openig/filter/PasswordReplayFilterHeaplet.java
index 795f7ce0a..fdf332c40 100644
--- a/openig-core/src/main/java/org/forgerock/openig/filter/PasswordReplayFilterHeaplet.java
+++ b/openig-core/src/main/java/org/forgerock/openig/filter/PasswordReplayFilterHeaplet.java
@@ -12,6 +12,7 @@
  * information: "Portions Copyright [year] [name of copyright owner]".
  *
  * Copyright 2015-2016 ForgeRock AS.
+ * Portions Copyrighted 2026 3A Systems, LLC.
  */
 
 package org.forgerock.openig.filter;
@@ -76,9 +77,9 @@
  *     <li>Extracted patterns need to have at least a single regex group, the first one is always used</li>
  * </ul>
  *
- * <h3>Usage examples:</h3>
+ * <h2>Usage examples:</h2>
  *
- * <h4>Authenticate on behalf of the user when a login page is GET</h4>
+ * <h3>Authenticate on behalf of the user when a login page is GET</h3>
  *
  * <p>When a {@literal GET} request to the login page is intercepted, OpenIG will generate an alternative
  * authentication request and send it in place of the original request. The response is forwarded as-is to the caller.
@@ -99,7 +100,7 @@
  *     }
  * </pre>
  *
- * <h4>Authenticate on behalf of the user when a login page is returned</h4>
+ * <h3>Authenticate on behalf of the user when a login page is returned</h3>
  *
  * <p>When a response that is identified to be a login page is intercepted, OpenIG will generate an authentication
  * request and send it. The authentication response is ignored ATM. Then OpenIG replays the original incoming request.
diff --git a/openig-core/src/main/java/org/forgerock/openig/handler/router/RouterHandler.java b/openig-core/src/main/java/org/forgerock/openig/handler/router/RouterHandler.java
index 310e787f2..0349d537b 100644
--- a/openig-core/src/main/java/org/forgerock/openig/handler/router/RouterHandler.java
+++ b/openig-core/src/main/java/org/forgerock/openig/handler/router/RouterHandler.java
@@ -104,7 +104,7 @@
  *     synchronously.</li>
  * </ul>
  * In both cases, the default value is 10 seconds.
- * <br/>
+ * <br>
  * <p>In addition to regular route JSON files, this handler now also recognises OpenAPI spec files
  * ({@code .json}, {@code .yaml}, {@code .yml}) dropped into the same routes directory.
  * When {@code openApiValidation.mockMode} is {@code true}, auto-generated routes use an
diff --git a/openig-core/src/main/java/org/forgerock/openig/heap/GenericHeaplet.java b/openig-core/src/main/java/org/forgerock/openig/heap/GenericHeaplet.java
index 6153834dc..a40d8f3b6 100644
--- a/openig-core/src/main/java/org/forgerock/openig/heap/GenericHeaplet.java
+++ b/openig-core/src/main/java/org/forgerock/openig/heap/GenericHeaplet.java
@@ -13,6 +13,7 @@
  *
  * Copyright 2010-2011 ApexIdentity Inc.
  * Portions Copyright 2011-2016 ForgeRock AS.
+ * Portions Copyrighted 2026 3A Systems, LLC.
  */
 
 package org.forgerock.openig.heap;
@@ -39,7 +40,7 @@
 /**
  * A generic base class for heaplets with automatically injected fields.
  * <p>
- * If the object created is an instance of {@link GenericHeapObject}, it is then
+ * If the object created is an instance of {@code GenericHeapObject}, it is then
  * automatically injected with {@code logger} and {@code storage} objects.
  */
 public abstract class GenericHeaplet implements Heaplet {
diff --git a/openig-core/src/main/java/org/forgerock/openig/heap/Keys.java b/openig-core/src/main/java/org/forgerock/openig/heap/Keys.java
index b5fb279e4..2d7b96c55 100644
--- a/openig-core/src/main/java/org/forgerock/openig/heap/Keys.java
+++ b/openig-core/src/main/java/org/forgerock/openig/heap/Keys.java
@@ -12,6 +12,7 @@
  * information: "Portions copyright [year] [name of copyright owner]".
  *
  * Copyright 2015-2016 ForgeRock AS.
+ * Portions Copyrighted 2026 3A Systems, LLC.
  */
 package org.forgerock.openig.heap;
 
@@ -99,7 +100,7 @@ public final class Keys {
     public static final String SESSION_FACTORY_HEAP_KEY = "Session";
 
     /**
-     * Key to retrieve an implementation of a {@link org.forgerock.util.Factory<org.forgerock.http.io.Buffer>} instance
+     * Key to retrieve an implementation of a {@link org.forgerock.util.Factory}&lt;{@link org.forgerock.http.io.Buffer}&gt; instance
      * from the {@link org.forgerock.openig.heap.Heap}.
      */
     public static final String TEMPORARY_STORAGE_HEAP_KEY = "TemporaryStorage";
diff --git a/openig-core/src/main/java/org/forgerock/openig/util/JsonValues.java b/openig-core/src/main/java/org/forgerock/openig/util/JsonValues.java
index 20cbcd96f..711bd38c9 100644
--- a/openig-core/src/main/java/org/forgerock/openig/util/JsonValues.java
+++ b/openig-core/src/main/java/org/forgerock/openig/util/JsonValues.java
@@ -212,7 +212,7 @@ public static Function<JsonValue, String, JsonValueException> heapObjectNameOrPo
 
     /**
      * Returns a function that will evaluate all String nodes. Transformation is applied
-     * recursively. <p>Malformed expressions are ignored e.g: <tt>"$$$${{"</tt>
+     * recursively. <p>Malformed expressions are ignored e.g: <code>"$$$${{"</code>
      * and their values are not changed. <p>When an error occurs during the
      * evaluation of an expression, the value is set to {@code null} because we
      * cannot differentiate successful evaluations or failed ones.
@@ -225,7 +225,7 @@ public static Function<JsonValue, JsonValue, JsonValueException> evaluated() {
 
     /**
      * Returns a function that will evaluate all String nodes. Transformation is applied
-     * recursively. <p>Malformed expressions are ignored e.g: <tt>"$$$${{"</tt>
+     * recursively. <p>Malformed expressions are ignored e.g: <code>"$$$${{"</code>
      * and their values are not changed. <p>When an error occurs during the
      * evaluation of an expression, the value is set to {@code null} because we
      * cannot differentiate successful evaluations or failed ones.
diff --git a/pom.xml b/pom.xml
index 6033c767d..728191976 100644
--- a/pom.xml
+++ b/pom.xml
@@ -38,7 +38,10 @@
     <maven.min.version>3.1.0</maven.min.version>
 	<maven.compiler.target>11</maven.compiler.target>
     <maven.compiler.source>11</maven.compiler.source>
-    
+
+    <!-- Javadoc doclint level, inherited by all modules. -->
+    <doclint>all,-missing</doclint>
+
     <!--  ForgeRock build tools and Checkstyle versions (to avoid many checkstyle errors with ForgeRock Parent 2.0.10) -->
     <forgerockBuildToolsVersion>1.0.3</forgerockBuildToolsVersion>
     <checkstylePluginVersion>2.9.1</checkstylePluginVersion>
@@ -859,7 +862,8 @@
 		    </execution>
 		  </executions>
 		  <configuration>
-		  	<doclint>none</doclint>
+		  	<doclint>${doclint}</doclint>
+			<failOnWarnings>true</failOnWarnings>
 			<notimestamp>true</notimestamp>
 		  </configuration>
 		</plugin>
@@ -956,7 +960,7 @@
 		<plugin>
 			<groupId>org.apache.maven.plugins</groupId>
 			<artifactId>maven-javadoc-plugin</artifactId>
-			<version>3.10.1</version>
+			<version>3.12.0</version>
 			<configuration>
 			</configuration>
 		</plugin>