Enable Javadoc doclint errors (#2831)

Author: 8Keep

.github/workflows/main.yml

@@ -107,6 +107,29 @@ jobs:
           path: |
             **/build/reports/spotbugs/**
 
+  JavadocDoclint:
+    name: Run Javadoc Doclint
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - name: Setup the java environment
+        uses: actions/setup-java@v5
+        with:
+          distribution: 'temurin'
+          java-version: '25'
+      - name: Validate the Gradle wrapper
+        uses: gradle/actions/wrapper-validation@v6.1.0
+      - name: Run Javadoc doclint
+        run: |
+          ./gradlew -PenableJavadocError=true javadoc mergedJavadoc --console=plain --stacktrace
+      - name: Report Javadoc doclint failure
+        if: failure()
+        run: |
+          echo "::notice title=Javadoc doclint failed::Javadoc warnings were found. Run ./gradlew -PenableJavadocError=true javadoc mergedJavadoc locally to reproduce."
+
   ScreenshotTests:
     name: Run Screenshot Tests
     runs-on: ubuntu-latest

build.gradle

@@ -198,8 +198,15 @@ tasks.register('mergedJavadoc', Javadoc) {
     title = 'jMonkeyEngine3'
     destinationDir = file("dist/javadoc")
 
+    def javadocErrorsEnabled = findProperty('enableJavadocError') == 'true'
+    failOnError = javadocErrorsEnabled
     options.encoding = 'UTF-8'
-    options.addStringOption('Xdoclint:none', '-quiet')
+    if (javadocErrorsEnabled) {
+        options.addBooleanOption('Werror', true)
+        options.addBooleanOption('Xdoclint:all,-missing', true)
+    } else {
+        options.addStringOption('Xdoclint:none', '-quiet')
+    }
 
     options.overview = file("javadoc-overview.html")
     source = mergedJavadocSubprojects.collect { project(it).sourceSets.main.allJava }

common.gradle

@@ -70,7 +70,14 @@ jar {
 }
 
 javadoc {
-    failOnError = false
+    def javadocErrorsEnabled = rootProject.findProperty('enableJavadocError') == 'true'
+    failOnError = javadocErrorsEnabled
+    if (javadocErrorsEnabled) {
+        options.addBooleanOption('Werror', true)
+        options.addBooleanOption('Xdoclint:all,-missing', true)
+    } else {
+        options.addStringOption('Xdoclint:none', '-quiet')
+    }
     options.memberLevel = org.gradle.external.javadoc.JavadocMemberLevel.PROTECTED
     options.docTitle = "jMonkeyEngine ${jmeFullVersion} ${project.name} Javadoc"
     options.windowTitle = "jMonkeyEngine ${jmeFullVersion} ${project.name} Javadoc"
@@ -79,7 +86,6 @@ javadoc {
     options.use = "true"
     options.charSet = "UTF-8"
     options.encoding = "UTF-8"
-    options.addStringOption('Xdoclint:none', '-quiet')
     source = sourceSets.main.allJava // main only, exclude tests
 }
 

javadoc-overview.html

@@ -12,7 +12,7 @@
 in Java aimed at wide accessibility and quick deployment to desktop, 
 web, and mobile platforms.
 
-<h3>Key Features</h3>
+<h1>Key Features</h1>
 <ul>
 <li>Free, open-source software (under the New BSD license) – Use our free engine for commercial, educational, or hobby game development</li>
 <li>Minimal adaptations for cross-compatibility – Create games that run on any OpenGL 2 and 3-ready device with the Java Virtual Machine – web, desktop, or mobile.</li>
@@ -23,4 +23,3 @@ <h3>Key Features</h3>
 
 </body>
 </html>
-

jme3-core/src/main/java/com/jme3/anim/tween/action/Action.java

@@ -39,12 +39,12 @@
 /**
  * Wraps an array of Tween actions into an action object.
  * 
- * <p>
- * Notes :
+ * <p>Notes:</p>
+ * <ul>
  * <li> The sequence of tweens is determined by {@link com.jme3.anim.tween.Tweens} utility class and the {@link BaseAction} interpolates that sequence. </li>
  * <li> This implementation mimics the {@link com.jme3.anim.tween.AbstractTween}, but it delegates the interpolation method {@link Tween#interpolate(double)}
  * to the {@link BlendableAction} class. </li>
- * </p>
+ * </ul>
  * 
  * Created by Nehon.
  *
@@ -64,12 +64,12 @@ public abstract class Action implements JmeCloneable, Tween {
 
     /**
      * Instantiates an action object that wraps a tween actions array by extracting their actions to the collection {@link Action#actions}.
-     * <p>
-     * Notes :
+     * <p>Notes:</p>
+     * <ul>
      * <li> If intentions are to wrap some tween actions, then subclasses have to call this constructor, examples : {@link BlendableAction} and {@link BlendAction}. </li>
      * <li> If intentions are to make an implementation of {@link Action} that shouldn't wrap tweens of actions, then subclasses shouldn't call this
      * constructor, examples : {@link ClipAction} and {@link BaseAction}. </li>
-     * </p> 
+     * </ul>
      *
      * @param tweens the tween actions to be wrapped (not null).
      */    
@@ -117,13 +117,13 @@ public double getSpeed() {
 
     /**
      * Alters the speedup factor applied by the layer running this action.
-     * <p>
-     * Notes:
+     * <p>Notes:</p>
+     * <ul>
      * <li> This factor controls the animation direction, if the speed is a positive value then the animation will run forward and vice versa. </li>
      * <li> The speed factor gets applied, inside the {@link com.jme3.anim.AnimLayer}, on each interpolation step by this formula : time += tpf * action.getSpeed() * composer.globalSpeed. </li>
      * <li> Default speed is 1.0, it plays the animation clips at their normal speed. </li>
      * <li> Setting the speed factor to Zero will stop the animation, while setting it to a negative number will play the animation in a backward fashion. </li>
-     * </p>
+     * </ul>
      * 
      * @param speed the speed of frames.
      */

jme3-core/src/main/java/com/jme3/anim/tween/action/BaseAction.java

@@ -55,7 +55,6 @@
  * //run the action within this layer
  * animComposer.setCurrentAction("basicAction", ActionState.class.getSimpleName());
  * </pre>
- * </p>
  * Created by Nehon.
  */
 public class BaseAction extends Action {

jme3-core/src/main/java/com/jme3/anim/tween/action/BlendSpace.java

@@ -31,37 +31,34 @@
  */
 package com.jme3.anim.tween.action;
 
+import com.jme3.anim.util.HasLocalTransform;
+import com.jme3.math.Transform;
+
 /**
  * A provider interface which provides a value {@link BlendSpace#getWeight()} to control the blending between 2 successive actions in a {@link BlendAction}.
  * The blending weight is a read-only value, and it can be manipulated using the arbitrary value {@link BlendSpace#setValue(float)} during the application runtime.
  * 
- * <p>
- * Notes about the blending action and its relations with the blending weight:
+ * <p>Notes about the blending action and its relations with the blending weight:</p>
  * <ul>
  * <li> Blending is the action of mixing between 2 successive animation {@link BlendableAction}s by interpolating their transforms and 
  * then applying the result on the assigned {@link HasLocalTransform} object, the {@link BlendSpace} provides this blending action with a blend weight value. </li>
  * <li> The blend weight is the value for the interpolation for the target transforms. </li>
  * <li> The blend weight value must be in this interval [0, 1]. </li>
  * </ul>
- * </p>
  * 
- * <p>
- * Different blending weight case scenarios managed by {@link BlendAction} internally:
+ * <p>Different blending weight case scenarios managed by {@link BlendAction} internally:</p>
  * <ul>
- * <li> In case of (0 < Blending weight < 1), the blending is executed each update among 2 actions, the first action will use 
+ * <li> In case of (0 &lt; Blending weight &lt; 1), the blending is executed each update among 2 actions, the first action will use
  * a blend value of 1 and the second action will use the blend space weight as a value for the interpolation. </li>
  * <li> In case of (Blending weight = 0), the blending hasn't started yet, only the first action will be interpolated at (weight = 1). </li>
  * <li> In case of (Blending weight = 1), the blending is finished and only the second action will continue to run at (weight = 1). </li>
  * </ul>
- * </p>
  * 
- * <p>
- * Notes about the blending weight value:
+ * <p>Notes about the blending weight value:</p>
  * <ul>
  * <li> Negative values and values greater than 1 aren't allowed (i.e., extrapolations aren't allowed). </li>
  * <li> For more details, see {@link BlendAction#doInterpolate(double)} and {@link BlendAction#collectTransform(HasLocalTransform, Transform, float, BlendableAction)}. </li>
  * </ul>
- * </p> 
  *
  * Created by Nehon.
  * @see LinearBlendSpace an example of blendspace implementation

jme3-core/src/main/java/com/jme3/input/controls/MouseAxisTrigger.java

@@ -47,7 +47,7 @@ public class MouseAxisTrigger implements Trigger {
 
     /**
      * Create a new <code>MouseAxisTrigger</code>.
-     * <p>
+     *
      * @param mouseAxis Mouse axis. See AXIS_*** constants in {@link MouseInput}
      * @param negative True if listen to negative axis events, false if
      * listen to positive axis events.

jme3-core/src/main/java/com/jme3/material/logic/TechniqueDefLogic.java

@@ -91,7 +91,7 @@ public Shader makeCurrent(AssetManager assetManager, RenderManager renderManager
      * {@link #makeCurrent(com.jme3.asset.AssetManager, com.jme3.renderer.RenderManager, java.util.EnumSet, com.jme3.light.LightList, com.jme3.shader.DefineList)}.
      * @param geometry The geometry to render
      * @param lights Lights which influence the geometry.
-     * @param lastTexUnit the index of the most recently used texture unit
+     * @param lastBindUnits the most recently used bind units
      */
     public void render(RenderManager renderManager, Shader shader, Geometry geometry, LightList lights, BindUnits lastBindUnits);
 }

jme3-core/src/main/java/com/jme3/scene/Node.java

@@ -685,22 +685,23 @@ with BoundingSphere bounding volumes and collideWith(BoundingSphere).  Doing
      /**
      * Returns flat list of Spatials implementing the specified class AND
      * with name matching the specified pattern.
-     * <P>
+     *
      * Note that we are <i>matching</i> the pattern, therefore the pattern
      * must match the entire pattern (i.e. it behaves as if it is sandwiched
      * between "^" and "$").
      * You can set regex modes, like case insensitivity, by using the (?X)
      * or (?X:Y) constructs.
-     * </P> <P>
-     * By design, it is always safe to code loops like:<PRE>
+     *
+     * <p>By design, it is always safe to code loops like:</p>
+     * <PRE>
      *     for (Spatial spatial : node.descendantMatches(AClass.class, "regex"))
      * </PRE>
-     * <P>
+     *
      * "Descendants" does not include self, per the definition of the word.
      * To test for descendants AND self, you must do a
      * <code>node.matches(aClass, aRegex)</code> +
      * <code>node.descendantMatches(aClass, aRegex)</code>.
-     * <P>
+     *
      *
      * @param <T> the type of Spatial returned
      * @param spatialSubclass Subclass which matching Spatials must implement.