From 800940c2d71d9390d38f1945000d14180049bf57 Mon Sep 17 00:00:00 2001
From: Ray Healy <raymond.m.healy@gmail.com>
Date: Sat, 14 Mar 2026 09:36:45 -0400
Subject: [PATCH] trajectory/ballistics/models: Update documentation

---
 .../ballistics/models/BallisticModel.java     | 43 +++++++++++++++--
 .../models/ParabolicTimeOfFlightBM.java       | 47 ++++++++++++++++---
 .../ballistics/models/ReversableRadialBM.java |  9 ++--
 3 files changed, 86 insertions(+), 13 deletions(-)

diff --git a/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/BallisticModel.java b/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/BallisticModel.java
index 2f98288..304321c 100644
--- a/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/BallisticModel.java
+++ b/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/BallisticModel.java
@@ -7,13 +7,27 @@ import edu.wpi.first.units.Units;
 import edu.wpi.first.units.measure.Distance;
 import edu.wpi.first.units.measure.Time;
 
+/// Base class for ballistic models
+/// 
+/// The model is responsible for:
+///     - Tracking its launch and target positions (and relative stats)
+///     - Managing 
 public abstract class BallisticModel<P> {
-    protected Translation3d posLaunch;
-    protected Translation3d posTarget;
+    /// The launch position (i.e. where the projectile leaves the shooter)
+    protected final Translation3d posLaunch;
+    /// The target position (i.e. what we're trying to hit)
+    protected final Translation3d posTarget;
 
+    /// The position of posTarget relative to posLaunch
     protected final Translation3d targetPosRelative;
+    /// The horizontal disance of targetPosRelative
     protected final Distance relativeHorizontalDistance;
 
+    /**
+     * Constructo which sets the model
+     * @param posLaunch The inital posLaunch
+     * @param posTarget The inital posTarget
+     */
     public BallisticModel(Translation3d posLaunch, Translation3d posTarget) {
         this.posLaunch      = posLaunch;
         this.posTarget      = posTarget;
@@ -29,18 +43,36 @@ public abstract class BallisticModel<P> {
     //  Base getters
     //
 
+    /**
+     * Get the current launch position
+     * @return The current launch position
+     */
     public Translation3d getPosLaunch() {
         return this.posLaunch;
     }
 
+    /**
+     * Get the current target position
+     * @return The current target position
+     */
     public Translation3d getPosTarget() {
         return this.posTarget;
     }
 
+    /**
+     * Get the position of posTarget relative to posLaunch
+     *
+     * @return The position of posTarget relative to posLaunch
+     */
     public Translation3d getTargetPosRelative() {
         return this.targetPosRelative;
     }
 
+    /**
+     * Get the horizontal distance between posLaunch and posTarget
+     *
+     * @return The horizontal distance between posLaunch and posTarget
+     */
     public Distance getRelativeHorizontalDistance() {
         return this.relativeHorizontalDistance;
     }
@@ -50,6 +82,8 @@ public abstract class BallisticModel<P> {
     //
 
     /**
+     * Returns a recommended starting parameter
+     *
      * @return Returns a recommended starting parameter
      */
     public abstract P getInitParam();
@@ -72,7 +106,7 @@ public abstract class BallisticModel<P> {
     /**
      * Get an initial velocity (in the same coordinate space as posLaunch and
      * posTarget) which will pass thru posLaunch and posTarget with the given
-     * model configurations and parameters
+     * model configurations and parameters.
      *
      * @param param The parameters used to determine this candidate
      * @return The computed result for the given parameter
@@ -95,7 +129,8 @@ public abstract class BallisticModel<P> {
     //
 
     /**
-     * Check if a given parameter has had a computed velocity
+     * Check if a given parameter has had a computed velocity.
+     *
      * @param param The param to check
      * @return true iff the parameter has had a computed solution
      */
diff --git a/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/ParabolicTimeOfFlightBM.java b/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/ParabolicTimeOfFlightBM.java
index 5b0d247..76f9867 100644
--- a/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/ParabolicTimeOfFlightBM.java
+++ b/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/ParabolicTimeOfFlightBM.java
@@ -13,17 +13,35 @@ import edu.wpi.first.units.measure.LinearAcceleration;
 import edu.wpi.first.units.measure.Time;
 
 
+/**
+ * Parabolic ballistic model, with solutions computed from time of flight
+ */
 public class ParabolicTimeOfFlightBM extends ReversableRadialBM<Time> {
+    /** The linear acceleration of gravity in the +Z axis (positive is upwards) */
     public static final LinearAcceleration k_gravity = Units.MetersPerSecondPerSecond.of(-9.81);
 
-    protected final Time tofMin;
-    protected final Time tofMax;
-    protected final Time tofStep;
+    /** The minimum time of flight to consider */
+    protected final Time    tofMin;
+    /** The maximum time of flight to consider */
+    protected final Time    tofMax;
+    /** The step between parameters */
+    protected final Time    tofStep;
 
-    protected final Angle           azimuth;
+    /** The azimuth angle between posLaunch and posTarget */
+    protected final Angle   azimuth;
 
-    private HashSet<Double>         computedSeconds;
+    /** The times (in seconds) that have been computed for */
+    private HashSet<Double> computedSeconds;
 
+    /**
+     * Main constructor
+     * 
+     * @param posLaunch The position projectiles are launched from
+     * @param posTarget The target position for projectiles
+     * @param tofMin The minimum time of flight to consider
+     * @param tofMax The maximum time of flight to consider
+     * @param tofStep The timestep between candidate times of flight
+     */
     public ParabolicTimeOfFlightBM(
         Translation3d posLaunch, Translation3d posTarget,
         Time tofMin, Time tofMax, Time tofStep
@@ -48,21 +66,39 @@ public class ParabolicTimeOfFlightBM extends ReversableRadialBM<Time> {
     //  Base getters
     //
 
+    /**
+     * Gets the minimum time of flight
+     * @return the minimum time of flight
+     */
     public Time getTOFMin() {
         return this.tofMin;
     }
 
 
+    /**
+     * Get the maximum time of flight
+     * @return The maximum time of flight
+     */
     public Time getTOFMax() {
         return this.tofMax;
     }
 
 
+    /**
+     * Get the timestep between candidate times of flight
+     *
+     * @return The timestep between candidate times of flight
+     */
     public Time getTOFStep() {
         return this.tofStep;
     }
 
 
+    /**
+     * Get the computed azimuth angle from the launch position to the target position
+     *
+     * @return the computed azimuth angle from the launch position to the target position
+     */
     public Angle getAzimuth() {
         return this.azimuth;
     }
@@ -126,7 +162,6 @@ public class ParabolicTimeOfFlightBM extends ReversableRadialBM<Time> {
         return radialDistance.div(candidate.getHorizontalVelocity());
     }
 
-
     //
     //  Computed parameter check
     //
diff --git a/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/ReversableRadialBM.java b/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/ReversableRadialBM.java
index e5bf120..37533d9 100644
--- a/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/ReversableRadialBM.java
+++ b/lib/src/main/java/org/fairportrobotics/frc/robolib/trajectory/ballistics/models/ReversableRadialBM.java
@@ -22,11 +22,14 @@ public abstract class ReversableRadialBM<P> extends BallisticModel<P> {
     //
 
     /**
-     * Get the time taken to travel a given radial distance from posLaunch towards posTarget
+     * Get the time taken to travel a given radial distance from posLaunch
+     * towards posTarget
      *
      * @param candidate The generated velocity to compute against
-     * @param radialDistance The radial distance from posLaunch to posTarget to solve for
-     * @return The time it takes to travel radialDistance from posTarget towards posTarget
+     * @param radialDistance The radial distance from posLaunch to posTarget to
+     * solve for.
+     * @return The time it takes to travel radialDistance from posTarget towards
+     * posTarget
      */
     public abstract Time getTimeAtRadius(Velocity3d candidate, Distance radialDistance);