fix: javadoc warnings

.github/workflows/ci.yml

@@ -18,7 +18,6 @@ env:
   JAVA_VERSION: 21 # must be consistent with POM; see also dependabot config for any version limits
   JAVA_VERSION_LATEST: 25 # the latest `JAVA_VERSION` that we test with CI
   java_distribution: zulu
-  javadoc_version: 25 # newer than `JAVA_VERSION` for better javadoc
   groovy_version: 4.x
   CCDB_CONNECTION: 'sqlite:///${{ github.workspace }}/coatjava/etc/data/sqlite/ccdb.sqlite'
   nthreads: 1
@@ -353,7 +352,7 @@ jobs:
       - name: set up JDK
         uses: actions/setup-java@v5
         with:
-          java-version: ${{ env.javadoc_version }}
+          java-version: ${{ env.JAVA_VERSION }}
           distribution: ${{ env.java_distribution }}
           cache: maven
       - name: build coatjava javadocs # javadoc:aggregate output dir cannot be controlled, so assume the latest "standard" path and `mv` it

common-tools/clas-decay-tools/src/main/java/org/jlab/clas/decay/analysis/Particle.java

@@ -571,7 +571,7 @@ public double getRecMass() {
     }
 
     /**
-     * @param _recmass the _mass to set
+     * @param _mass the _mass to set
      */
     public void setRecMass(double _mass) {
         this._recmass = _mass;

common-tools/clas-detector/src/main/java/org/jlab/detector/helicity/HelicityGenerator.java

@@ -145,11 +145,11 @@ public void addState(HelicityBit bit) {
      * Let the user add a state to initialize the sequence.
      * 
      * This just calls {@link #addState(HelicityBit)} with the raw
-     * {@link #HelicityBit} from the given {@link #HelicityState}.
+     * {@link HelicityBit} from the given {@link HelicityState}.
      *
      * This must be the first helicity state in the next pattern.  States
      * must be added serially and without skipped patterns.  Requires
-     * {@link initialized} is false and a defined {@link #HelicityState}.
+     * {@link initialized} is false and a defined {@link HelicityState}.
      * 
      * @param state the HelicityState to add to the sequence.
      */

common-tools/clas-detector/src/main/java/org/jlab/detector/helicity/HelicitySequence.java

@@ -297,7 +297,7 @@ public HelicityBit predictGenerated(long timestamp) {
      * Get whether the pseudo-random generator is initialized.  This must be
      * true before calling the predict methods, because they require a working
      * generator.  The number of valid states required to intialize the generator
-     * is {@link HelicityGenerator.REGISTER_SIZE}.
+     * is {@link HelicityGenerator#REGISTER_SIZE}.
      * 
      * @return whether initialized 
      */

common-tools/clas-geometry/src/main/java/org/jlab/geom/detector/alert/AHDC/AlertDCWireIdentifier.java

@@ -171,7 +171,7 @@ else if (digit == 51) {
     /**
      * Convert layer number (from 0 to 7) to the superlayer-layer id (11,21,...,51)
      * 
-     * @param digit between 0 and 7
+     * @param num between 0 and 7
      * @return layer number between (11,21,...,51)
      */
     public static int number2layer(int num) {

common-tools/clas-geometry/src/main/java/org/jlab/geom/detector/fmt/FMTSuperlayer.java

@@ -7,13 +7,13 @@
 /**
  * A Forward Micromegas Tracker  (FMT) {@link org.jlab.geom.base.Superlayer Superlayer}.
  * <p>
- * Factory: {@link org.jlab.geom.detector.cnd.FMTFactory FMTFactory}<br> 
+ * Factory: {@link org.jlab.geom.detector.fmt.FMTFactory FMTFactory}<br> 
  * Hierarchy: 
  * <code>
- * {@link org.jlab.geom.detector.cnd.FMTDetector FMTDetector} → 
- * {@link org.jlab.geom.detector.cnd.FMTSector FMTSector} → 
- * <b>{@link org.jlab.geom.detector.cnd.FMTSuperlayer FMTSuperlayer}</b> → 
- * {@link org.jlab.geom.detector.cnd.FMTLayer FMTLayer} → 
+ * {@link org.jlab.geom.detector.fmt.FMTDetector FMTDetector} → 
+ * {@link org.jlab.geom.detector.fmt.FMTSector FMTSector} → 
+ * <b>{@link org.jlab.geom.detector.fmt.FMTSuperlayer FMTSuperlayer}</b> → 
+ * {@link org.jlab.geom.detector.fmt.FMTLayer FMTLayer} → 
  * {@link org.jlab.geom.component.TrackerStrip TrackerStrip}
  * </code>
  * 

common-tools/clas-io/src/main/java/org/jlab/io/base/BasicDataBank.java

@@ -565,13 +565,13 @@ public TableModel getTableModel(String mask) {
             if(entryMask.contains(columns[loop])==true||entryMask.size()<2){
                 for(int row = 0; row < nrows; row++){                    
                     if(this.byteContainer.containsKey(columns[loop])==true){
-                        objects[row][loop] = new Byte(this.getByte(columns[loop], row));
+                        objects[row][loop] = this.getByte(columns[loop], row);
                     }
                     if(this.shortContainer.containsKey(columns[loop])==true){
-                        objects[row][loop] = new Short(this.getShort(columns[loop], row));
+                        objects[row][loop] = this.getShort(columns[loop], row);
                     }
                     if(this.intContainer.containsKey(columns[loop])==true){
-                        objects[row][loop] = new Integer(this.getInt(columns[loop], row));
+                        objects[row][loop] = this.getInt(columns[loop], row);
                     }
                     if(this.floatContainer.containsKey(columns[loop])==true){
                         //objects[row][loop] = new Float(this.getFloat(columns[loop], row));
@@ -581,7 +581,7 @@ public TableModel getTableModel(String mask) {
                         objects[row][loop] = String.format("%12.5f",this.getDouble(columns[loop], row));
                     }
                     if(this.longContainer.containsKey(columns[loop])==true){
-                        objects[row][loop] = new Long(this.getLong(columns[loop], row));
+                        objects[row][loop] = this.getLong(columns[loop], row);
                     }
                 }
             }

common-tools/clas-jcsg/src/main/java/eu/mihosoft/vrl/v3d/VFX3DUtil.java

@@ -40,12 +40,12 @@
 import javafx.scene.transform.Rotate;
 
 /**
- * Utility class that allows to visualize meshes created with null {@link MathUtil#evaluateFunction(
+ * Utility class that allows to visualize meshes created with null {@code MathUtil#evaluateFunction(
  *   eu.mihosoft.vrl.javaone2013.math.Function2D,
  *   int, int, float, float, float, double, double, double, double)
  * }.
  *
- * @author Michael Hoffer <info@michaelhoffer.de>
+ * written by Michael Hoffer (info@michaelhoffer.de)
  */
 public class VFX3DUtil {
 

common-tools/clas-jcsg/src/main/java/eu/mihosoft/vrl/v3d/Vector3d.java

@@ -669,7 +669,7 @@ public Vector3d rotateZ(double angle) {
      * @param vector the vector to rotate
      * @param angle the angle of rotation
      *
-     * @author pdavies
+     * written by pdavies
      */
     public void rotate(Vector3d vector, double angle) {
         double m = vector.magnitude();
@@ -695,23 +695,23 @@ public void rotate(Vector3d vector, double angle) {
      * @param point the other point
      * @return a point at the geometric mean of the two given points
      *
-     * @author pdavies
+     * written by pdavies
      */
     public Vector3d midpoint(Vector3d point) {
         return lerp(point, 0.5);
     }
 
     /**
      * @return theta elevation (angle between vector and z axis)
-     * @author pdavies
+     * written by pdavies
      */
     public double theta() {
         return (this.magnitude() < 2e-6) ? 1.0 : Math.acos(this.z / this.magnitude()); // special case at mag = 0
     }
 
     /**
      * @return phi azimuth (angle between projection onto xy plane and x axis)
-     * @author pdavies
+     * written by pdavies
      */
     public double phi() {
         return Math.atan2(this.y, this.x);

common-tools/clas-jcsg/src/main/java/eu/mihosoft/vrl/v3d/ext/openjfx/importers/obj/FloatArrayList.java

@@ -94,7 +94,7 @@
  * @see Collection
  * @see List
  * @see LinkedList
- * @see Vector
+ * @see cnuphys.adaptiveSwim.geometry.Vector
  *
  * TODO replace with ObservableFloatArray
  */
@@ -358,7 +358,6 @@ public float[] toFloatArray() {
      *
      * @param index index of the element to return
      * @return the element at the specified position in this list
-     * @throws IndexOutOfBoundsException {@inheritDoc}
      */
     @Override public Float get(int index) {
         rangeCheck(index);
@@ -372,7 +371,6 @@ public float[] toFloatArray() {
      * @param index   index of the element to replace
      * @param element element to be stored at the specified position
      * @return the element previously at the specified position
-     * @throws IndexOutOfBoundsException {@inheritDoc}
      */
     @Override public Float set(int index, Float element) {
         rangeCheck(index);
@@ -400,7 +398,7 @@ public float[] toFloatArray() {
      *
      * @param index   index at which the specified element is to be inserted
      * @param element element to be inserted
-     * @throws IndexOutOfBoundsException {@inheritDoc}
+     * @throws IndexOutOfBoundsException
      */
     @Override public void add(int index, Float element) {
         rangeCheckForAdd(index);
@@ -419,7 +417,7 @@ public float[] toFloatArray() {
      *
      * @param index the index of the element to be removed
      * @return the element that was removed from the list
-     * @throws IndexOutOfBoundsException {@inheritDoc}
+     * @throws IndexOutOfBoundsException
      */
     @Override public Float remove(int index) {
         rangeCheck(index);
@@ -511,7 +509,7 @@ private void fastRemove(int index) {
      * @param index index at which to insert the first element from the specified collection
      * @param c     collection containing elements to be added to this list
      * @return <tt>true</tt> if this list changed as a result of the call
-     * @throws IndexOutOfBoundsException {@inheritDoc}
+     * @throws IndexOutOfBoundsException
      * @throws NullPointerException      if the specified collection is null
      */
     @Override public boolean addAll(int index, Collection<? extends Float> c) {
@@ -687,7 +685,7 @@ private void readObject(java.io.ObjectInputStream s)
      * </p>
      * <p>The returned list iterator is <a href="#fail-fast"><i>fail-fast</i></a>.
      *
-     * @throws IndexOutOfBoundsException {@inheritDoc}
+     * @throws IndexOutOfBoundsException
      */
     @Override public ListIterator<Float> listIterator(int index) {
         if (index < 0 || index > size)
@@ -840,8 +838,8 @@ private class ListItr extends Itr implements ListIterator<Float> {
      * that change the size of this list, or otherwise perturb it in such a fashion that iterations in progress may
      * yield incorrect results.)
      *
-     * @throws IndexOutOfBoundsException {@inheritDoc}
-     * @throws IllegalArgumentException  {@inheritDoc}
+     * @throws IndexOutOfBoundsException
+     * @throws IllegalArgumentException
      */
     @Override public List<Float> subList(int fromIndex, int toIndex) {
         subListRangeCheck(fromIndex, toIndex, size);

common-tools/clas-jcsg/src/main/java/eu/mihosoft/vrl/v3d/ext/openjfx/importers/obj/IntegerArrayList.java

@@ -359,7 +359,7 @@ public int[] toIntArray() {
      *
      * @param index index of the element to return
      * @return the element at the specified position in this list
-     * @throws IndexOutOfBoundsException {@inheritDoc}
+     * @throws IndexOutOfBoundsException
      */
     @Override public Integer get(int index) {
         rangeCheck(index);
@@ -373,7 +373,7 @@ public int[] toIntArray() {
      * @param index   index of the element to replace
      * @param element element to be stored at the specified position
      * @return the element previously at the specified position
-     * @throws IndexOutOfBoundsException {@inheritDoc}
+     * @throws IndexOutOfBoundsException
      */
     @Override public Integer set(int index, Integer element) {
         rangeCheck(index);
@@ -401,7 +401,7 @@ public int[] toIntArray() {
      *
      * @param index   index at which the specified element is to be inserted
      * @param element element to be inserted
-     * @throws IndexOutOfBoundsException {@inheritDoc}
+     * @throws IndexOutOfBoundsException
      */
     @Override public void add(int index, Integer element) {
         rangeCheckForAdd(index);
@@ -420,7 +420,7 @@ public int[] toIntArray() {
      *
      * @param index the index of the element to be removed
      * @return the element that was removed from the list
-     * @throws IndexOutOfBoundsException {@inheritDoc}
+     * @throws IndexOutOfBoundsException
      */
     @Override public Integer remove(int index) {
         rangeCheck(index);
@@ -512,7 +512,7 @@ private void fastRemove(int index) {
      * @param index index at which to insert the first element from the specified collection
      * @param c     collection containing elements to be added to this list
      * @return <tt>true</tt> if this list changed as a result of the call
-     * @throws IndexOutOfBoundsException {@inheritDoc}
+     * @throws IndexOutOfBoundsException
      * @throws NullPointerException      if the specified collection is null
      */
     @Override public boolean addAll(int index, Collection<? extends Integer> c) {
@@ -688,7 +688,7 @@ private void readObject(java.io.ObjectInputStream s)
      * </p>
      * <p>The returned list iterator is <a href="#fail-fast"><i>fail-fast</i></a>.
      *
-     * @throws IndexOutOfBoundsException {@inheritDoc}
+     * @throws IndexOutOfBoundsException
      */
     @Override public ListIterator<Integer> listIterator(int index) {
         if (index < 0 || index > size)
@@ -841,8 +841,8 @@ private class ListItr extends Itr implements ListIterator<Integer> {
      * that change the size of this list, or otherwise perturb it in such a fashion that iterations in progress may
      * yield incorrect results.)
      *
-     * @throws IndexOutOfBoundsException {@inheritDoc}
-     * @throws IllegalArgumentException  {@inheritDoc}
+     * @throws IndexOutOfBoundsException
+     * @throws IllegalArgumentException
      */
     @Override public List<Integer> subList(int fromIndex, int toIndex) {
         subListRangeCheck(fromIndex, toIndex, size);

common-tools/clas-jcsg/src/main/java/org/jlab/detector/geant4/v2/MPGD/trapezoid/MPGDTrapezoidStripFactory.java

@@ -33,8 +33,8 @@ protected MPGDTrapezoidStripFactory(MPGDTrapezoidConstants constants) {
 
     /**
      * Detector-specific hook: Must return the volume object given its
-     * name.Typically implemented by indexing geo.getAllVolumes() into a
-     * Map<String,Geant4Basic>.
+     * name.Typically implemented by indexing {@code geo.getAllVolumes()} into a
+     * {@code Map<String,Geant4Basic>}.
      *
      * @param name
      * @return

common-tools/clas-jcsg/src/main/java/org/jlab/detector/geant4/v2/RICHGeant4Factory.java

@@ -303,8 +303,8 @@ else  if(Layernr == 302){
     }
     /**
      * @author: gangel
-     * @param   layer nr, component nr
-     * Layer can be (Aerogel) 201,202,203,204,  (Planar Mirror) 301, (Spherical Mirror)302
+     * @param   Layer_nr Layer can be (Aerogel) 201,202,203,204,  (Planar Mirror) 301, (Spherical Mirror)302
+     * @param   Component_nr
      * @return: the G4Stl file
      */
     public G4Stl getStlComponent(int Layer_nr , int Component_nr){

common-tools/clas-jcsg/src/main/java/org/jlab/detector/geant4/v2/SVT/SVTVolumeFactory.java

@@ -98,6 +98,7 @@ public class SVTVolumeFactory
 	 * Default: false
 	 * @deprecated
 	 */
+        @Deprecated
 	public boolean HALFBOXES = false;
 
 

common-tools/clas-jcsg/src/main/java/org/jlab/detector/geant4/v2/SVT/Util.java

@@ -465,30 +465,6 @@ public static void scalePosition( Geant4Basic aVol, double aFactor )
 	}
 
 
-	/**
-	 * Recursively multiplies each linear dimension of the given volume and its children by the given scale factor.
-	 * 
-	 * @param aVol volume
-	 * @param aFactor scale factor
-	 * @deprecated
-	 */
-        /*
-	public static void scaleDimensions( Geant4Basic aVol, double aFactor, boolean bRecursive )
-	{
-		aVol.scaleDimensions( aFactor );
-		//aVol.scale( aFactor );
-
-		if( bRecursive )
-		{
-			List<Geant4Basic> children = aVol.getChildren();
-			for( int i = 0; i < children.size(); i++ )
-			{
-				scaleDimensions( children.get(i), aFactor, true ); // tail recursive
-			}
-		}
-	}
-	*/
-
 	/**
 	 * Translates the given volume's position by the given shifts. 
 	 * 

common-tools/clas-jcsg/src/main/java/org/jlab/detector/volume/Geant4Basic.java

@@ -347,16 +347,12 @@ public Line3d getLineZ() {
         //return new Line3d(new Vector3d(0, 0, 0), new Vector3d(0, 0, 0));
     }
 
-    /**
-     * @author pdavies
-     */
+    // written by pdavies
     public void setPosition(double x, double y, double z) {
         setPosition(new Vector3d(x, y, z));
     }
 
-    /**
-     * @author pdavies
-     */
+    // written by pdavies
     public void setPosition(Vector3d position) {
         this.translate(position.minus(this.getLocalPosition()));
     }

common-tools/clas-jcsg/src/main/java/org/jlab/geometry/prim/Triangle3d.java

@@ -91,7 +91,7 @@ else if(!interpoints.isEmpty()) {
     }
 
     /**
-     * @author pdavies
+     * written by pdavies
      */
 	public Vector3d center() {
 		double x = 0;
@@ -107,7 +107,7 @@ public Vector3d center() {
 	}
 
 	/**
-	 * @author pdavies
+	 * written by pdavies
 	 */
 	public Vector3d point(int index) {
 		if( index < 0 || index > 2 )

common-tools/clas-logging/src/main/java/org/jlab/logging/SplitLogManager.java

@@ -25,7 +25,7 @@ public Logger getLogger(String name) {
 
   /**
    * add a new {@link Logger} instance
-   * @param name the name of the logger
+   * @param logger the logger
    * @return {@code true} if the argument logger was registered successfully, {@code false} if a logger of that name already exists
    */
   @Override