Fix javadoc warnings (#2266)

Persuant to #1093, I added as many docstrings as I could, at least for
things I knew about. Some of the classes I just suppressed the Javadoc
warnings in because they aren't particularly useful to document. This
gets us down to less than 100 Javadoc warnings in total. Docs for core
classes on the C++ side were also added for parity.

photon-targeting/src/main/java/org/photonvision/targeting/MultiTargetPNPResult.java

@@ -30,8 +30,11 @@ public class MultiTargetPNPResult
     private static final int MAX_IDS = 32;
 
     public PnpResult estimatedPose = new PnpResult();
+
+    /** The fiducial IDs used to calculate this multi-target result. */
     public List<Short> fiducialIDsUsed = List.of();
 
+    /** Used for serialization and tests. */
     public MultiTargetPNPResult() {}
 
     public MultiTargetPNPResult(PnpResult results, List<Short> ids) {
@@ -72,9 +75,10 @@ public class MultiTargetPNPResult
                 + "]";
     }
 
+    /** MultiTargetPNPResult protobuf for serialization. */
     public static final MultiTargetPNPResultProto proto = new MultiTargetPNPResultProto();
 
-    // tODO!
+    /** MultiTargetPNPResult PhotonStruct for serialization. */
     public static final MultiTargetPNPResultSerde photonStruct = new MultiTargetPNPResultSerde();
 
     @Override

photon-targeting/src/main/java/org/photonvision/targeting/PhotonPipelineMetadata.java

@@ -48,17 +48,29 @@ public class PhotonPipelineMetadata implements PhotonStructSerializable<PhotonPi
         this(-1, -1, -1, Long.MAX_VALUE);
     }
 
-    /** Returns the time between image capture and publish to NT */
+    /**
+     * Returns the time between image capture and publish to NT
+     *
+     * @return The time in milliseconds
+     */
     public double getLatencyMillis() {
         return (publishTimestampMicros - captureTimestampMicros) / 1e3;
     }
 
-    /** The time that this image was captured, in the coprocessor's time base. */
+    /**
+     * The time that this image was captured, in the coprocessor's time base.
+     *
+     * @return The time in microseconds
+     */
     public long getCaptureTimestampMicros() {
         return captureTimestampMicros;
     }
 
-    /** The time that this result was published to NT, in the coprocessor's time base. */
+    /**
+     * The time that this result was published to NT, in the coprocessor's time base.
+     *
+     * @return The time in microseconds
+     */
     public long getPublishTimestampMicros() {
         return publishTimestampMicros;
     }
@@ -66,6 +78,8 @@ public class PhotonPipelineMetadata implements PhotonStructSerializable<PhotonPi
     /**
      * The number of non-empty frames processed by this camera since boot. Useful to checking if a
      * camera is alive.
+     *
+     * @return The number of non-empty frames
      */
     public long getSequenceID() {
         return sequenceID;

photon-targeting/src/main/java/org/photonvision/targeting/PhotonPipelineResult.java

@@ -31,13 +31,13 @@ public class PhotonPipelineResult
         implements ProtobufSerializable, PhotonStructSerializable<PhotonPipelineResult> {
     private static boolean HAS_WARNED = false;
 
-    // Frame capture metadata
+    /** Frame capture metadata. */
     public PhotonPipelineMetadata metadata;
 
-    // Targets to store.
+    /** The list of targets detected by the pipeline. */
     public List<PhotonTrackedTarget> targets = new ArrayList<>();
 
-    // Multi-tag result
+    /** The multitag result, if using an AprilTag pipeline with Multi-Target Estimation enabled. */
     public Optional<MultiTargetPNPResult> multitagResult;
 
     /** Constructs an empty pipeline result. */
@@ -53,6 +53,7 @@ public class PhotonPipelineResult
      *     coprocessor captured the image this result contains the targeting info of
      * @param publishTimestampMicros The time, in uS in the coprocessor's timebase, that the
      *     coprocessor published targeting info
+     * @param timeSinceLastPong The time since the last Time Sync Pong in uS.
      * @param targets The list of targets identified by the pipeline.
      */
     public PhotonPipelineResult(
@@ -76,6 +77,7 @@ public class PhotonPipelineResult
      *     captured the image this result contains the targeting info of
      * @param publishTimestamp The time, in uS in the coprocessor's timebase, that the coprocessor
      *     published targeting info
+     * @param timeSinceLastPong The time since the last Time Sync Pong in uS.
      * @param targets The list of targets identified by the pipeline.
      * @param result Result from multi-target PNP.
      */
@@ -155,8 +157,11 @@ public class PhotonPipelineResult
     }
 
     /**
-     * Return the latest multi-target result. Be sure to check
-     * getMultiTagResult().estimatedPose.isPresent before using the pose estimate!
+     * Return the latest multi-target result. Be sure to check {@code getMultiTagResult().isPresent()}
+     * before using the pose estimate!
+     *
+     * @return The multi-target result. Empty if there's no multi-target result/Multi-Target
+     *     Estimation is disabled in the UI.
      */
     public Optional<MultiTargetPNPResult> getMultiTagResult() {
         return multitagResult;
@@ -212,7 +217,10 @@ public class PhotonPipelineResult
         return true;
     }
 
+    /** PhotonPipelineResult PhotonStruct for serialization. */
     public static final PhotonPipelineResultSerde photonStruct = new PhotonPipelineResultSerde();
+
+    /** PhotonPipelineResult Protobuf for serialization. */
     public static final PhotonPipelineResultProto proto = new PhotonPipelineResultProto();
 
     @Override

photon-targeting/src/main/java/org/photonvision/targeting/PhotonTrackedTarget.java

@@ -25,28 +25,63 @@ import org.photonvision.struct.PhotonTrackedTargetSerde;
 import org.photonvision.targeting.proto.PhotonTrackedTargetProto;
 import org.photonvision.targeting.serde.PhotonStructSerializable;
 
+/** Information about a detected target. */
 public class PhotonTrackedTarget
         implements ProtobufSerializable, PhotonStructSerializable<PhotonTrackedTarget> {
     private static final int MAX_CORNERS = 8;
 
+    /** The yaw of the target in degrees, with left being the positive direction. */
     public double yaw;
+
+    /** The pitch of the target in degrees, with up being the positive direction. */
     public double pitch;
+
+    /** The area (how much of the camera feed the bounding box takes up) as a percentage (0-100). */
     public double area;
+
+    /** The skew of the target in degrees, with counterclockwise being the positive direction. */
     public double skew;
+
+    /** The fiducial ID, or -1 if it doesn't exist for this target. */
     public int fiducialId;
+
+    /** The object detection class ID, or -1 if it doesn't exist for this target. */
     public int objDetectId;
+
+    /** The object detection confidence, or -1 if it doesn't exist for this target. */
     public float objDetectConf;
+
+    /** The transform with the lowest reprojection error */
     public Transform3d bestCameraToTarget;
+
+    /** The transform with the highest reprojection error */
     public Transform3d altCameraToTarget;
+
+    /** The ratio (best:alt) of reprojection errors */
     public double poseAmbiguity;
 
-    // Corners from the min-area rectangle bounding the target
+    /** Corners from the min-area rectangle bounding the target */
     public List<TargetCorner> minAreaRectCorners;
 
-    // Corners from whatever corner detection method was used
+    /** Corners from the corner detection method used */
     public List<TargetCorner> detectedCorners;
 
-    /** Construct a tracked target, given exactly 4 corners */
+    /**
+     * Construct a tracked target, given exactly 4 corners
+     *
+     * @param yaw The yaw of the target
+     * @param pitch The pitch of the target
+     * @param area The area of the target as a percentage of the camera image
+     * @param skew The skew of the target
+     * @param fiducialId The fiduical tag ID
+     * @param classId The object detection class ID
+     * @param objDetectConf The object detection confidence
+     * @param pose The best camera to target transform
+     * @param altPose The alternate camera to target transform
+     * @param ambiguity The ambiguity (best:alternate ratio of reprojection errors) of the target
+     * @param minAreaRectCorners The corners of minimum area bounding box of the target
+     * @param detectedCorners The detected corners of the target
+     */
     public PhotonTrackedTarget(
             double yaw,
             double pitch,
@@ -80,9 +115,8 @@ public class PhotonTrackedTarget
         this.poseAmbiguity = ambiguity;
     }
 
-    public PhotonTrackedTarget() {
-        // TODO Auto-generated constructor stub
-    }
+    /** Used for serialization. */
+    public PhotonTrackedTarget() {}
 
     public double getYaw() {
         return yaw;
@@ -92,6 +126,11 @@ public class PhotonTrackedTarget
         return pitch;
     }
 
+    /**
+     * The area (how much of the camera feed the bounding box takes up) as a percentage (0-100).
+     *
+     * @return The area as a percentage
+     */
     public double getArea() {
         return area;
     }
@@ -100,19 +139,29 @@ public class PhotonTrackedTarget
         return skew;
     }
 
-    /** Get the fiducial ID, or -1 if not set. */
+    /**
+     * Get the fiducial ID, or -1 if it doesn't exist for this target.
+     *
+     * @return The fiducial ID
+     */
     public int getFiducialId() {
         return fiducialId;
     }
 
-    /** Get the object detection class ID number, or -1 if not set. */
+    /**
+     * Get the object detection class ID number, or -1 if it doesn't exist for this target.
+     *
+     * @return The object detection class ID
+     */
     public int getDetectedObjectClassID() {
         return objDetectId;
     }
 
     /**
-     * Get the object detection confidence, or -1 if not set. This will be between 0 and 1, with 1
-     * indicating most confidence, and 0 least.
+     * Get the object detection confidence, or -1 if it doesn't exist for this target. This will be
+     * between 0 and 1, with 1 indicating most confidence, and 0 least.
+     *
+     * @return The object detection confidence
      */
     public float getDetectedObjectConfidence() {
         return objDetectConf;
@@ -122,6 +171,8 @@ public class PhotonTrackedTarget
      * Get the ratio of best:alternate pose reprojection errors, called ambiguity. This is between 0
      * and 1 (0 being no ambiguity, and 1 meaning both have the same reprojection error). Numbers
      * above 0.2 are likely to be ambiguous. -1 if invalid.
+     *
+     * @return The pose ambiguity
      */
     public double getPoseAmbiguity() {
         return poseAmbiguity;
@@ -130,6 +181,8 @@ public class PhotonTrackedTarget
     /**
      * Return a list of the 4 corners in image space (origin top left, x right, y down), in no
      * particular order, of the minimum area bounding rectangle of this target
+     *
+     * @return The list of corners
      */
     public List<TargetCorner> getMinAreaRectCorners() {
         return minAreaRectCorners;
@@ -147,6 +200,8 @@ public class PhotonTrackedTarget
      * V      |       |
      * +Y     0 ----- 1
      * </pre>
+     *
+     * @return The list of detected corners for this target
      */
     public List<TargetCorner> getDetectedCorners() {
         return detectedCorners;
@@ -155,6 +210,8 @@ public class PhotonTrackedTarget
     /**
      * Get the transform that maps camera space (X = forward, Y = left, Z = up) to object/fiducial tag
      * space (X forward, Y left, Z up) with the lowest reprojection error
+     *
+     * @return The transform with the lowest reprojection error (the best)
      */
     public Transform3d getBestCameraToTarget() {
         return bestCameraToTarget;
@@ -163,6 +220,8 @@ public class PhotonTrackedTarget
     /**
      * Get the transform that maps camera space (X = forward, Y = left, Z = up) to object/fiducial tag
      * space (X forward, Y left, Z up) with the highest reprojection error
+     *
+     * @return The transform with the highest reprojection error (the alternate)
      */
     public Transform3d getAlternateCameraToTarget() {
         return altCameraToTarget;
@@ -253,7 +312,10 @@ public class PhotonTrackedTarget
                 + "]";
     }
 
+    /** PhotonTrackedTarget protobuf for serialization. */
     public static final PhotonTrackedTargetProto proto = new PhotonTrackedTargetProto();
+
+    /** PhotonTrackedTarget PhotonStruct for serialization. */
     public static final PhotonTrackedTargetSerde photonStruct = new PhotonTrackedTargetSerde();
 
     @Override

photon-targeting/src/main/java/org/photonvision/targeting/PnpResult.java

@@ -33,6 +33,7 @@ import org.photonvision.targeting.serde.PhotonStructSerializable;
  * <p>Note that the coordinate frame of these transforms depends on the implementing solvePnP
  * method.
  */
+@SuppressWarnings("doclint")
 public class PnpResult implements ProtobufSerializable, PhotonStructSerializable<PnpResult> {
     /**
      * The best-fit transform. The coordinate frame of this transform depends on the method which gave
@@ -133,7 +134,10 @@ public class PnpResult implements ProtobufSerializable, PhotonStructSerializable
                 + "]";
     }
 
+    /** PnpResult protobuf for serialization. */
     public static final PNPResultProto proto = new PNPResultProto();
+
+    /** PnpResult PhotonStruct for serialization. */
     public static final PnpResultSerde photonStruct = new PnpResultSerde();
 
     @Override

photon-targeting/src/main/java/org/photonvision/targeting/TargetCorner.java

@@ -28,6 +28,7 @@ import org.photonvision.targeting.serde.PhotonStructSerializable;
  * Represents a point in an image at the corner of the minimum-area bounding rectangle, in pixels.
  * Origin at the top left, plus-x to the right, plus-y down.
  */
+@SuppressWarnings("doclint")
 public class TargetCorner implements ProtobufSerializable, PhotonStructSerializable<TargetCorner> {
     public double x;
     public double y;
@@ -59,7 +60,10 @@ public class TargetCorner implements ProtobufSerializable, PhotonStructSerializa
         return "(" + x + "," + y + ')';
     }
 
+    /** TargetCorner protobuf for serialization. */
     public static final TargetCornerProto proto = new TargetCornerProto();
+
+    /** TargetCorner PhotonStruct for serialization. */
     public static final TargetCornerSerde photonStruct = new TargetCornerSerde();
 
     @Override

photon-targeting/src/main/java/org/photonvision/targeting/serde/PhotonStructSerializable.java

@@ -20,5 +20,10 @@ package org.photonvision.targeting.serde;
 import org.photonvision.common.dataflow.structures.PacketSerde;
 
 public interface PhotonStructSerializable<T> {
+    /**
+     * Returns the PhotonStruct serializer for this type.
+     *
+     * @return The PhotonStruct serializer
+     */
     PacketSerde<T> getSerde();
 }