From 9730032866ea8d00db8da4eff898de5d698cf059 Mon Sep 17 00:00:00 2001
From: Tyler Veness <calcmogul@gmail.com>
Date: Sat, 17 Sep 2022 00:16:40 -0700
Subject: [PATCH] [wpimath] Document LQR and KalmanFilter exceptions (#4418)

---
 .../wpi/first/math/controller/LinearQuadraticRegulator.java   | 4 ++++
 .../main/java/edu/wpi/first/math/estimator/KalmanFilter.java  | 1 +
 .../native/include/frc/controller/LinearQuadraticRegulator.h  | 4 ++++
 wpimath/src/main/native/include/frc/estimator/KalmanFilter.h  | 1 +
 4 files changed, 10 insertions(+)

diff --git a/wpimath/src/main/java/edu/wpi/first/math/controller/LinearQuadraticRegulator.java b/wpimath/src/main/java/edu/wpi/first/math/controller/LinearQuadraticRegulator.java
index e244c5f1c2..7f16576bcf 100644
--- a/wpimath/src/main/java/edu/wpi/first/math/controller/LinearQuadraticRegulator.java
+++ b/wpimath/src/main/java/edu/wpi/first/math/controller/LinearQuadraticRegulator.java
@@ -44,6 +44,7 @@ public class LinearQuadraticRegulator<States extends Num, Inputs extends Num, Ou
    * @param qelms The maximum desired error tolerance for each state.
    * @param relms The maximum desired control effort for each input.
    * @param dtSeconds Discretization timestep.
+   * @throws IllegalArgumentException If the system is uncontrollable.
    */
   public LinearQuadraticRegulator(
       LinearSystem<States, Inputs, Outputs> plant,
@@ -66,6 +67,7 @@ public class LinearQuadraticRegulator<States extends Num, Inputs extends Num, Ou
    * @param qelms The maximum desired error tolerance for each state.
    * @param relms The maximum desired control effort for each input.
    * @param dtSeconds Discretization timestep.
+   * @throws IllegalArgumentException If the system is uncontrollable.
    */
   @SuppressWarnings({"ParameterName", "LocalVariableName"})
   public LinearQuadraticRegulator(
@@ -90,6 +92,7 @@ public class LinearQuadraticRegulator<States extends Num, Inputs extends Num, Ou
    * @param Q The state cost matrix.
    * @param R The input cost matrix.
    * @param dtSeconds Discretization timestep.
+   * @throws IllegalArgumentException If the system is uncontrollable.
    */
   @SuppressWarnings({"LocalVariableName", "ParameterName"})
   public LinearQuadraticRegulator(
@@ -141,6 +144,7 @@ public class LinearQuadraticRegulator<States extends Num, Inputs extends Num, Ou
    * @param R The input cost matrix.
    * @param N The state-input cross-term cost matrix.
    * @param dtSeconds Discretization timestep.
+   * @throws IllegalArgumentException If the system is uncontrollable.
    */
   @SuppressWarnings({"ParameterName", "LocalVariableName"})
   public LinearQuadraticRegulator(
diff --git a/wpimath/src/main/java/edu/wpi/first/math/estimator/KalmanFilter.java b/wpimath/src/main/java/edu/wpi/first/math/estimator/KalmanFilter.java
index c992d2fa16..a6c298bfe3 100644
--- a/wpimath/src/main/java/edu/wpi/first/math/estimator/KalmanFilter.java
+++ b/wpimath/src/main/java/edu/wpi/first/math/estimator/KalmanFilter.java
@@ -52,6 +52,7 @@ public class KalmanFilter<States extends Num, Inputs extends Num, Outputs extend
    * @param stateStdDevs Standard deviations of model states.
    * @param measurementStdDevs Standard deviations of measurements.
    * @param dtSeconds Nominal discretization timestep.
+   * @throws IllegalArgumentException If the system is unobservable.
    */
   @SuppressWarnings("LocalVariableName")
   public KalmanFilter(
diff --git a/wpimath/src/main/native/include/frc/controller/LinearQuadraticRegulator.h b/wpimath/src/main/native/include/frc/controller/LinearQuadraticRegulator.h
index 5f4f099a35..50d65662b9 100644
--- a/wpimath/src/main/native/include/frc/controller/LinearQuadraticRegulator.h
+++ b/wpimath/src/main/native/include/frc/controller/LinearQuadraticRegulator.h
@@ -40,6 +40,7 @@ class LinearQuadraticRegulator {
    * @param Qelems The maximum desired error tolerance for each state.
    * @param Relems The maximum desired control effort for each input.
    * @param dt     Discretization timestep.
+   * @throws std::invalid_argument If the system is uncontrollable.
    */
   template <int Outputs>
   LinearQuadraticRegulator(const LinearSystem<States, Inputs, Outputs>& plant,
@@ -54,6 +55,7 @@ class LinearQuadraticRegulator {
    * @param Qelems The maximum desired error tolerance for each state.
    * @param Relems The maximum desired control effort for each input.
    * @param dt     Discretization timestep.
+   * @throws std::invalid_argument If the system is uncontrollable.
    */
   LinearQuadraticRegulator(const Matrixd<States, States>& A,
                            const Matrixd<States, Inputs>& B,
@@ -68,6 +70,7 @@ class LinearQuadraticRegulator {
    * @param Q  The state cost matrix.
    * @param R  The input cost matrix.
    * @param dt Discretization timestep.
+   * @throws std::invalid_argument If the system is uncontrollable.
    */
   LinearQuadraticRegulator(const Matrixd<States, States>& A,
                            const Matrixd<States, Inputs>& B,
@@ -84,6 +87,7 @@ class LinearQuadraticRegulator {
    * @param R  The input cost matrix.
    * @param N  The state-input cross-term cost matrix.
    * @param dt Discretization timestep.
+   * @throws std::invalid_argument If the system is uncontrollable.
    */
   LinearQuadraticRegulator(const Matrixd<States, States>& A,
                            const Matrixd<States, Inputs>& B,
diff --git a/wpimath/src/main/native/include/frc/estimator/KalmanFilter.h b/wpimath/src/main/native/include/frc/estimator/KalmanFilter.h
index aa8db1e745..2121284550 100644
--- a/wpimath/src/main/native/include/frc/estimator/KalmanFilter.h
+++ b/wpimath/src/main/native/include/frc/estimator/KalmanFilter.h
@@ -50,6 +50,7 @@ class KalmanFilter {
    * @param stateStdDevs       Standard deviations of model states.
    * @param measurementStdDevs Standard deviations of measurements.
    * @param dt                 Nominal discretization timestep.
+   * @throws std::invalid_argument If the system is unobservable.
    */
   KalmanFilter(LinearSystem<States, Inputs, Outputs>& plant,
                const StateArray& stateStdDevs,