[wpimath] Clean up profile classes (#6311)

* Reorder functions so they match between languages
* Copy more complete JavaDocs to C++
* Fix incorrect description for time parameter of
  TrapezoidProfile.calculate()

wpimath/src/main/native/include/frc/trajectory/ExponentialProfile.h

@@ -81,7 +81,7 @@ class ExponentialProfile {
   class Constraints {
    public:
     /**
-     * Construct constraints for an ExponentialProfile.
+     * Constructs constraints for an ExponentialProfile.
      *
      * @param maxInput maximum unsigned input voltage
      * @param A The State-Space 1x1 system matrix.
@@ -91,7 +91,7 @@ class ExponentialProfile {
         : maxInput{maxInput}, A{A}, B{B} {}
 
     /**
-     * Construct constraints for an ExponentialProfile from characteristics.
+     * Constructs constraints for an ExponentialProfile from characteristics.
      *
      * @param maxInput maximum unsigned input voltage
      * @param kV The velocity gain.
@@ -130,7 +130,7 @@ class ExponentialProfile {
   };
 
   /**
-   * Construct a ExponentialProfile.
+   * Constructs a ExponentialProfile.
    *
    * @param constraints The constraints on the profile, like maximum input.
    */
@@ -142,41 +142,72 @@ class ExponentialProfile {
   ExponentialProfile& operator=(ExponentialProfile&&) = default;
 
   /**
-   * Calculate the correct position and velocity for the profile at a time t
-   * where the current state is at time t = 0.
+   * Calculates the position and velocity for the profile at a time t where the
+   * current state is at time t = 0.
+   *
+   * @param t How long to advance from the current state toward the desired
+   *     state.
+   * @param current The current state.
+   * @param goal The desired state when the profile is complete.
+   * @return The position and velocity of the profile at time t.
    */
   State Calculate(const units::second_t& t, const State& current,
                   const State& goal) const;
 
   /**
-   * Calculate the point after which the fastest way to reach the goal state is
+   * Calculates the point after which the fastest way to reach the goal state is
    * to apply input in the opposite direction.
+   *
+   * @param current The current state.
+   * @param goal The desired state when the profile is complete.
+   * @return The position and velocity of the profile at the inflection point.
    */
   State CalculateInflectionPoint(const State& current, const State& goal) const;
 
   /**
-   * Calculate the time it will take for this profile to reach the goal state.
+   * Calculates the time it will take for this profile to reach the goal state.
+   *
+   * @param current The current state.
+   * @param goal The desired state when the profile is complete.
+   * @return The total duration of this profile.
    */
   units::second_t TimeLeftUntil(const State& current, const State& goal) const;
 
   /**
-   * Calculate the time it will take for this profile to reach the inflection
+   * Calculates the time it will take for this profile to reach the inflection
    * point, and the time it will take for this profile to reach the goal state.
+   *
+   * @param current The current state.
+   * @param goal The desired state when the profile is complete.
+   * @return The timing information for this profile.
    */
   ProfileTiming CalculateProfileTiming(const State& current,
                                        const State& goal) const;
 
  private:
   /**
-   * Calculate the point after which the fastest way to reach the goal state is
+   * Calculates the point after which the fastest way to reach the goal state is
    * to apply input in the opposite direction.
+   *
+   * @param current The current state.
+   * @param goal The desired state when the profile is complete.
+   * @param input The signed input applied to this profile from the current
+   *     state.
+   * @return The position and velocity of the profile at the inflection point.
    */
   State CalculateInflectionPoint(const State& current, const State& goal,
                                  const Input_t& input) const;
 
   /**
-   * Calculate the time it will take for this profile to reach the inflection
+   * Calculates the time it will take for this profile to reach the inflection
    * point, and the time it will take for this profile to reach the goal state.
+   *
+   * @param current The current state.
+   * @param inflectionPoint The inflection point of this profile.
+   * @param goal The desired state when the profile is complete.
+   * @param input The signed input applied to this profile from the current
+   *     state.
+   * @return The timing information for this profile.
    */
   ProfileTiming CalculateProfileTiming(const State& current,
                                        const State& inflectionPoint,
@@ -184,40 +215,70 @@ class ExponentialProfile {
                                        const Input_t& input) const;
 
   /**
-   * Calculate the velocity reached after t seconds when applying an input from
-   * the initial state.
-   */
-  Velocity_t ComputeVelocityFromTime(const units::second_t& time,
-                                     const Input_t& input,
-                                     const State& initial) const;
-
-  /**
-   * Calculate the position reached after t seconds when applying an input from
+   * Calculates the position reached after t seconds when applying an input from
    * the initial state.
+   *
+   * @param t The time since the initial state.
+   * @param input The signed input applied to this profile from the initial
+   *     state.
+   * @param initial The initial state.
+   * @return The distance travelled by this profile.
    */
   Distance_t ComputeDistanceFromTime(const units::second_t& time,
                                      const Input_t& input,
                                      const State& initial) const;
 
   /**
-   * Calculate the distance reached at the same time as the given velocity when
-   * applying the given input from the initial state.
+   * Calculates the velocity reached after t seconds when applying an input from
+   * the initial state.
+   *
+   * @param t The time since the initial state.
+   * @param input The signed input applied to this profile from the initial
+   *     state.
+   * @param initial The initial state.
+   * @return The distance travelled by this profile.
    */
-  Distance_t ComputeDistanceFromVelocity(const Velocity_t& velocity,
-                                         const Input_t& input,
-                                         const State& initial) const;
+  Velocity_t ComputeVelocityFromTime(const units::second_t& time,
+                                     const Input_t& input,
+                                     const State& initial) const;
 
   /**
-   * Calculate the time required to reach a specified velocity given the initial
-   * velocity.
+   * Calculates the time required to reach a specified velocity given the
+   * initial velocity.
+   *
+   * @param velocity The goal velocity.
+   * @param input The signed input applied to this profile from the initial
+   *     state.
+   * @param initial The initial velocity.
+   * @return The time required to reach the goal velocity.
    */
   units::second_t ComputeTimeFromVelocity(const Velocity_t& velocity,
                                           const Input_t& input,
                                           const Velocity_t& initial) const;
 
   /**
-   * Calculate the velocity at which input should be reversed in order to reach
+   * Calculates the distance reached at the same time as the given velocity when
+   * applying the given input from the initial state.
+   *
+   * @param velocity The velocity reached by this profile
+   * @param input The signed input applied to this profile from the initial
+   *     state.
+   * @param initial The initial state.
+   * @return The distance reached when the given velocity is reached.
+   */
+  Distance_t ComputeDistanceFromVelocity(const Velocity_t& velocity,
+                                         const Input_t& input,
+                                         const State& initial) const;
+
+  /**
+   * Calculates the velocity at which input should be reversed in order to reach
    * the goal state from the current state.
+   *
+   * @param input The signed input applied to this profile from the current
+   *     state.
+   * @param current The current state.
+   * @param goal The goal state.
+   * @return The inflection velocity.
    */
   Velocity_t SolveForInflectionVelocity(const Input_t& input,
                                         const State& current,
@@ -226,8 +287,11 @@ class ExponentialProfile {
   /**
    * Returns true if the profile should be inverted.
    *
-   * <p>The profile is inverted if we should first apply negative input in order
-   * to reach the goal state.
+   * The profile is inverted if we should first apply negative input in order to
+   * reach the goal state.
+   *
+   * @param current The initial state (usually the current state).
+   * @param goal The desired state when the profile is complete.
    */
   bool ShouldFlipInput(const State& current, const State& goal) const;
 

wpimath/src/main/native/include/frc/trajectory/ExponentialProfile.inc

@@ -50,23 +50,6 @@ ExponentialProfile<Distance, Input>::CalculateInflectionPoint(
   return CalculateInflectionPoint(current, goal, u);
 }
 
-template <class Distance, class Input>
-typename ExponentialProfile<Distance, Input>::State
-ExponentialProfile<Distance, Input>::CalculateInflectionPoint(
-    const State& current, const State& goal, const Input_t& input) const {
-  auto u = input;
-
-  if (current == goal) {
-    return current;
-  }
-
-  auto inflectionVelocity = SolveForInflectionVelocity(u, current, goal);
-  auto inflectionPosition =
-      ComputeDistanceFromVelocity(inflectionVelocity, -u, goal);
-
-  return {inflectionPosition, inflectionVelocity};
-}
-
 template <class Distance, class Input>
 units::second_t ExponentialProfile<Distance, Input>::TimeLeftUntil(
     const State& current, const State& goal) const {
@@ -86,6 +69,23 @@ ExponentialProfile<Distance, Input>::CalculateProfileTiming(
   return CalculateProfileTiming(current, inflectionPoint, goal, u);
 }
 
+template <class Distance, class Input>
+typename ExponentialProfile<Distance, Input>::State
+ExponentialProfile<Distance, Input>::CalculateInflectionPoint(
+    const State& current, const State& goal, const Input_t& input) const {
+  auto u = input;
+
+  if (current == goal) {
+    return current;
+  }
+
+  auto inflectionVelocity = SolveForInflectionVelocity(u, current, goal);
+  auto inflectionPosition =
+      ComputeDistanceFromVelocity(inflectionVelocity, -u, goal);
+
+  return {inflectionPosition, inflectionVelocity};
+}
+
 template <class Distance, class Input>
 typename ExponentialProfile<Distance, Input>::ProfileTiming
 ExponentialProfile<Distance, Input>::CalculateProfileTiming(

wpimath/src/main/native/include/frc/trajectory/TrapezoidProfile.h

@@ -99,14 +99,14 @@ class TrapezoidProfile {
   };
 
   /**
-   * Construct a TrapezoidProfile.
+   * Constructs a TrapezoidProfile.
    *
    * @param constraints The constraints on the profile, like maximum velocity.
    */
   TrapezoidProfile(Constraints constraints);  // NOLINT
 
   /**
-   * Construct a TrapezoidProfile.
+   * Constructs a TrapezoidProfile.
    *
    * @param constraints The constraints on the profile, like maximum velocity.
    * @param goal        The desired state when the profile is complete.
@@ -127,10 +127,12 @@ class TrapezoidProfile {
   TrapezoidProfile& operator=(TrapezoidProfile&&) = default;
 
   /**
-   * Calculate the correct position and velocity for the profile at a time t
-   * where the beginning of the profile was at time t = 0.
+   * Calculates the position and velocity for the profile at a time t where the
+   * current state is at time t = 0.
    *
-   * @param t The time since the beginning of the profile.
+   * @param t How long to advance from the current state toward the desired
+   *     state.
+   * @return The position and velocity of the profile at time t.
    * @deprecated Pass the desired and current state into calculate instead of
    * constructing a new TrapezoidProfile with the desired and current state
    */
@@ -141,12 +143,14 @@ class TrapezoidProfile {
   State Calculate(units::second_t t) const;
 
   /**
-   * Calculate the correct position and velocity for the profile at a time t
-   * where the beginning of the profile was at time t = 0.
+   * Calculates the position and velocity for the profile at a time t where the
+   * current state is at time t = 0.
    *
-   * @param t The time since the beginning of the profile.
-   * @param current     The initial state (usually the current state).
-   * @param goal        The desired state when the profile is complete.
+   * @param t How long to advance from the current state toward the desired
+   *     state.
+   * @param current The current state.
+   * @param goal The desired state when the profile is complete.
+   * @return The position and velocity of the profile at time t.
    */
   State Calculate(units::second_t t, State current, State goal);
 
@@ -154,21 +158,25 @@ class TrapezoidProfile {
    * Returns the time left until a target distance in the profile is reached.
    *
    * @param target The target distance.
+   * @return The time left until a target distance in the profile is reached.
    */
   units::second_t TimeLeftUntil(Distance_t target) const;
 
   /**
    * Returns the total time the profile takes to reach the goal.
+   *
+   * @return The total time the profile takes to reach the goal.
    */
   units::second_t TotalTime() const { return m_endDeccel; }
 
   /**
    * Returns true if the profile has reached the goal.
    *
-   * The profile has reached the goal if the time since the profile started
-   * has exceeded the profile's total time.
+   * The profile has reached the goal if the time since the profile started has
+   * exceeded the profile's total time.
    *
    * @param t The time since the beginning of the profile.
+   * @return True if the profile has reached the goal.
    */
   bool IsFinished(units::second_t t) const { return t >= TotalTime(); }
 
@@ -179,7 +187,7 @@ class TrapezoidProfile {
    * The profile is inverted if goal position is less than the initial position.
    *
    * @param initial The initial state (usually the current state).
-   * @param goal    The desired state when the profile is complete.
+   * @param goal The desired state when the profile is complete.
    */
   static bool ShouldFlipAcceleration(const State& initial, const State& goal) {
     return initial.position > goal.position;