maven-javadoc-plugin: Enable legacyMode to bypass jzy3d JPMS error

While at it: Add class-level Javadocs, escape HTML entities in doc comments, and resolve lint warnings

Author: tferr

pom.xml

@@ -192,6 +192,7 @@
 				<artifactId>maven-javadoc-plugin</artifactId>
 				<configuration>
 					<legacyMode>true</legacyMode>
+					<detectJavaApiLink>false</detectJavaApiLink>
 					<failOnError>false</failOnError>
 				</configuration>
 			</plugin>

src/main/java/sc/fiji/snt/analysis/AbstractConvexHull.java

@@ -68,14 +68,19 @@ protected <T extends SNTPoint> AbstractConvexHull(final Collection<T> points) {
         boundarySize = -1;
 	}
 
+    /** Computes the convex hull from the input points. */
     public abstract void compute();
 
+    /** Returns the area (2D) or volume (3D) of this convex hull. */
     public abstract double size();
 
+    /** Returns the perimeter (2D) or surface area (3D) of this convex hull. */
     public abstract double boundarySize();
 
+    /** Returns the intersection of this convex hull with the given hull(s). */
     public abstract AbstractConvexHull intersection(final AbstractConvexHull... convexHull);
 
+    /** Returns the bounding-box intersection of this hull with the given hull(s). */
     public BoundingBox intersectionBox(final AbstractConvexHull... convexHulls) {
         BoundingBox intersectionBb = new BoundingBox(points);
         for (final AbstractConvexHull convexHull : convexHulls)

src/main/java/sc/fiji/snt/analysis/sholl/gui/ShollOverlay.java

@@ -48,8 +48,10 @@
 import ij.measure.Calibration;
 
 /**
- * @author Tiago Ferreira
+ * Renders Sholl analysis results as graphical overlays on an image,
+ * including concentric shells, sampling points, and intersection counts.
  *
+ * @author Tiago Ferreira
  */
 public class ShollOverlay implements ProfileProperties {
 

src/main/java/sc/fiji/snt/analysis/sholl/gui/ShollPlot.java

@@ -53,8 +53,10 @@
 import sc.fiji.snt.util.ShollPoint;
 
 /**
- * @author Tiago Ferreira
+ * An ImageJ {@link Plot} for displaying Sholl analysis profiles, including
+ * sampled data, fitted curves, and descriptive statistics.
  *
+ * @author Tiago Ferreira
  */
 public class ShollPlot extends Plot {
 

src/main/java/sc/fiji/snt/annotation/BrainAnnotation.java

@@ -43,44 +43,47 @@ public interface BrainAnnotation {
 	/** Character constant representing any hemisphere (null character) */
 	public char ANY_HEMISPHERE = '\u0000';
 
-	/** @return the compartment's unique id */
+	/** Returns the compartment's unique id. */
 	public int id();
 
-	/** @return the compartment's name */
+	/** Returns the compartment's name. */
 	public String name();
 
-	/** @return the compartment's acronym */
+	/** Returns the compartment's acronym. */
 	public String acronym();
 
-	/** @return the compartment's alias(es) */
+	/** Returns the compartment's alias(es). */
 	public String[] aliases();
 
-	/** @return the mesh associated with this compartment */
+	/** Returns the mesh associated with this compartment. */
 	public OBJMesh getMesh();
 
-	/** @return whether this compartment is a sub-compartment of {@code annotation} */
+	/** Returns whether this compartment is a sub-compartment of {@code annotation}. */
 	public boolean isChildOf(BrainAnnotation annotation);
 
-	/** @return whether this compartment is a parentCompartment of {@code annotation} */
+	/** Returns whether this compartment is a parent of {@code parentCompartment}. */
 	public boolean isParentOf(final BrainAnnotation parentCompartment);
 
+	/** Returns the ontology depth of this compartment. */
 	public int getOntologyDepth();
 
-	/** @return whether a mesh is available for this compartment */
+	/** Returns whether a mesh is available for this compartment. */
 	public boolean isMeshAvailable();
 
 	/**
+	 * Returns the ancestor of this compartment at the specified level.
+	 *
 	 * @param level the ancestor level as negative 1-based index. E.g., {@code -1}
 	 *              retrieves the last ancestor (parent), {@code -2} retrieves the
 	 *              second to last, etc
-	 * @return the ancestor of this compartment at the nth level
+	 * @return the ancestor at the given level
 	 */
 	public BrainAnnotation getAncestor(final int level);
 
-	/** @return the parent of this compartment */
+	/** Returns the parent of this compartment. */
 	public BrainAnnotation getParent();
 
-	/** @return the display color of this compartment (if known) */
+	/** Returns the display color of this compartment (if known). */
 	public ColorRGB color();
 
 	public static char getHemisphereFlag(final String hemisphere) {

src/main/java/sc/fiji/snt/gui/cmds/AddTextAnnotationCmd.java

@@ -44,6 +44,9 @@
 @Plugin(type = Command.class, visible = false, label = "Add Annotation Label...", initializer = "init")
 public class AddTextAnnotationCmd extends InteractiveCommand {
 
+	/** Creates a new AddTextAnnotationCmd instance. */
+	public AddTextAnnotationCmd() {}
+
 	@Parameter(label = "Text", required = false, description = "Font size")
 	private String string;
 
@@ -118,7 +121,7 @@ private int getStyle(final String style) {
 		}
 	}
 
-	/* IDE debug method **/
+	/** IDE debug method. */
 	public static void main(final String[] args) {
 		GuiUtils.setLookAndFeel();
 		final ImageJ ij = new ImageJ();

src/main/java/sc/fiji/snt/tracing/AbstractSearch.java

@@ -49,8 +49,11 @@ public abstract class AbstractSearch implements SearchInterface, Runnable {
 
     protected final RandomAccessibleInterval<? extends RealType<?>> img;
     protected final RandomAccess<? extends RealType<?>> imgAccess;
+    /** The width of the search image in pixels. */
     public final int imgWidth;
+    /** The height of the search image in pixels. */
     public final int imgHeight;
+    /** The depth (number of slices) of the search image. */
     public final int imgDepth;
     protected final long xMin;
     protected final long yMin;
@@ -198,8 +201,10 @@ protected void precomputeNeighborDistances() {
         }
     }
 
+    /** Registers a callback to receive progress updates during the search. */
     public abstract void addProgressListener(SearchProgressCallback callback);
 
+    /** Prints the current search status to the log. */
     public abstract void printStatus();
 
     /*
@@ -208,6 +213,7 @@ protected void precomputeNeighborDistances() {
      */
     protected abstract void reportPointsInSearch();
 
+    /** Returns the total number of points evaluated so far during the search. */
     public abstract long pointsConsideredInSearch();
 
 }

src/main/java/sc/fiji/snt/tracing/auto/AbstractAutoTracer.java

@@ -58,6 +58,9 @@
  */
 public abstract class AbstractAutoTracer implements AutoTracer {
 
+    /** Creates a new AbstractAutoTracer instance. */
+    protected AbstractAutoTracer() {}
+
     protected Roi somaRoi;
     protected int somaRoiZPosition = -1;  // Z-slice (0-indexed), -1 if unset
     protected int rootStrategy = ROI_UNSET;

src/main/java/sc/fiji/snt/tracing/auto/AbstractGWDTTracer.java

@@ -64,9 +64,11 @@
  */
 public abstract class AbstractGWDTTracer<T extends RealType<T>> extends AbstractAutoTracer {
 
-    // Fast Marching states
+    /** Fast Marching state: voxel has not yet been reached. */
     public static final byte FAR = 0;
+    /** Fast Marching state: voxel is in the narrow-band trial set. */
     public static final byte TRIAL = 1;
+    /** Fast Marching state: voxel distance has been finalized. */
     public static final byte ALIVE = 2;
 
     // Input
@@ -817,13 +819,13 @@ private double calculateRadiusFromImage(final long[] pos, final RandomAccess<T>
      * APP2-style dark node and segment pruning.
      * <p>
      * Phase 1: Dark Node Pruning (iterative)
-     * - For each leaf, if intensity <= background threshold, remove the leaf
+     * - For each leaf, if intensity &lt;= background threshold, remove the leaf
      * - Repeat until no more dark leaves found
      * <p>
      * Phase 2: Dark Segment Pruning
      * - For each terminal branch (path from leaf to branch point):
-     * - Delete if average intensity <= background threshold, OR
-     * - Delete if >= 20% of nodes are dark (intensity <= threshold)
+     * - Delete if average intensity &lt;= background threshold, OR
+     * - Delete if &gt;= 20% of nodes are dark (intensity &lt;= threshold)
      */
     protected void darkNodeAndSegmentPruning(final DirectedWeightedGraph graph, final double effectiveThreshold) {
         final SWCPoint root = findGraphRoot(graph);
@@ -1444,6 +1446,7 @@ protected long posToIndex(final long[] pos) {
         return posToIndex(pos, dims);
     }
 
+    /** Converts an N-dimensional position to a flat array index using row-major order. */
     public static long posToIndex(final long[] pos, final long[] dims) {
         long idx = 0;
         long stride = 1;

src/main/java/sc/fiji/snt/tracing/image/ListSearchImage.java

@@ -30,6 +30,9 @@
 import java.util.Iterator;
 
 /**
+ * A {@link SearchImage} backed by an ImgLib2 {@link ListImg}, providing
+ * list-based storage for path-search data structures.
+ *
  * @author Cameron Arshadi
  */
 public class ListSearchImage<V> implements SearchImage<V> {