[docs] Build with JavaDoc 17 and add missing docs (#6220)

Co-authored-by: Sam Carlberg <sam.carlberg@gmail.com>

wpiunits/src/main/java/edu/wpi/first/units/Current.java

@@ -23,6 +23,17 @@ public class Current extends Unit<Current> {
     super(Current.class, toBaseConverter, fromBaseConverter, name, symbol);
   }
 
+  /**
+   * Constructs a unit of power equivalent to this unit of electrical current multiplied by another
+   * unit of voltage. For example, {@code Amps.times(Volts)} will return a unit of power equivalent
+   * to one Watt; {@code Amps.times(Millivolts)} will return a unit of power equivalent to a
+   * milliwatt, and so on.
+   *
+   * @param voltage the voltage unit to multiply by
+   * @param name the name of the resulting unit of power
+   * @param symbol the symbol used to represent the unit of power
+   * @return the power unit
+   */
   public Power times(Unit<Voltage> voltage, String name, String symbol) {
     return new Power(this.toBaseUnits(1) * voltage.toBaseUnits(1), name, symbol);
   }

wpiunits/src/main/java/edu/wpi/first/units/Dimensionless.java

@@ -15,7 +15,7 @@ public class Dimensionless extends Unit<Dimensionless> {
    * @param name the name of the unit
    * @param symbol the symbol of the unit
    */
-  protected Dimensionless(double baseUnitEquivalent, String name, String symbol) {
+  Dimensionless(double baseUnitEquivalent, String name, String symbol) {
     super(Dimensionless.class, baseUnitEquivalent, name, symbol);
   }
 

wpiunits/src/main/java/edu/wpi/first/units/Energy.java

@@ -14,12 +14,12 @@ package edu.wpi.first.units;
  * {@link Units} class.
  */
 public class Energy extends Unit<Energy> {
-  protected Energy(
+  Energy(
       UnaryFunction toBaseConverter, UnaryFunction fromBaseConverter, String name, String symbol) {
     super(Energy.class, toBaseConverter, fromBaseConverter, name, symbol);
   }
 
-  protected Energy(double baseUnitEquivalent, String name, String symbol) {
+  Energy(double baseUnitEquivalent, String name, String symbol) {
     super(Energy.class, baseUnitEquivalent, name, symbol);
   }
 }

wpiunits/src/main/java/edu/wpi/first/units/Mult.java

@@ -8,7 +8,9 @@ import edu.wpi.first.units.collections.LongToObjectHashMap;
 import java.util.Objects;
 
 /**
- * A combinatory unit type that is equivalent to the product of two other others.
+ * A combinatory unit type that is equivalent to the product of two other others. Note that
+ * algebraic reduction is not possible in Java's generic type system, so {@code Mult<A, B>} is not
+ * type-compatible with {@code Mult<B, A>}!
  *
  * @param <A> the type of the first unit in the result
  * @param <B> the type of the second unit in the result
@@ -20,6 +22,14 @@ public class Mult<A extends Unit<A>, B extends Unit<B>> extends Unit<Mult<A, B>>
   @SuppressWarnings("rawtypes")
   private static final LongToObjectHashMap<Mult> cache = new LongToObjectHashMap<>();
 
+  /**
+   * Creates a new product unit. Consider using {@link #combine} instead of manually calling this
+   * constructor.
+   *
+   * @param baseType the base type representing the unit product
+   * @param a the first unit of the product
+   * @param b the second unit of the product
+   */
   protected Mult(Class<? extends Mult<A, B>> baseType, A a, B b) {
     super(
         baseType,
@@ -58,10 +68,20 @@ public class Mult<A extends Unit<A>, B extends Unit<B>> extends Unit<Mult<A, B>>
     return mult;
   }
 
+  /**
+   * Gets the first unit of the product.
+   *
+   * @return the first unit
+   */
   public A unitA() {
     return m_unitA;
   }
 
+  /**
+   * Gets the second unit of the product.
+   *
+   * @return the second unit
+   */
   public B unitB() {
     return m_unitB;
   }

wpiunits/src/main/java/edu/wpi/first/units/Per.java

@@ -11,7 +11,8 @@ import java.util.Objects;
  * Generic combinatory unit type that represents the proportion of one unit to another, such as
  * Meters per Second or Radians per Celsius.
  *
- * <p>Note: {@link Velocity} is used to represent the velocity dimension.
+ * <p>Note: {@link Velocity} is used to represent the velocity dimension, rather than {@code
+ * Per<Distance, Time>}.
  *
  * @param <N> the type of the numerator unit
  * @param <D> the type of the denominator unit
@@ -27,6 +28,14 @@ public class Per<N extends Unit<N>, D extends Unit<D>> extends Unit<Per<N, D>> {
   @SuppressWarnings("rawtypes")
   private static final LongToObjectHashMap<Per> cache = new LongToObjectHashMap<>();
 
+  /**
+   * Creates a new proportional unit derived from the ratio of one unit to another. Consider using
+   * {@link #combine} instead of manually calling this constructor.
+   *
+   * @param baseType the base type representing the unit ratio
+   * @param numerator the numerator unit
+   * @param denominator the denominator unit
+   */
   protected Per(Class<Per<N, D>> baseType, N numerator, D denominator) {
     super(
         baseType,
@@ -70,10 +79,20 @@ public class Per<N extends Unit<N>, D extends Unit<D>> extends Unit<Per<N, D>> {
     return newUnit;
   }
 
+  /**
+   * Gets the numerator unit. For a {@code Per<A, B>}, this will return the {@code A} unit.
+   *
+   * @return the numerator unit
+   */
   public N numerator() {
     return m_numerator;
   }
 
+  /**
+   * Gets the denominator unit. For a {@code Per<A, B>}, this will return the {@code B} unit.
+   *
+   * @return the denominator unit
+   */
   public D denominator() {
     return m_denominator;
   }

wpiunits/src/main/java/edu/wpi/first/units/UnaryFunction.java

@@ -6,6 +6,13 @@ package edu.wpi.first.units;
 
 import java.util.Objects;
 
+/**
+ * A function that accepts a single {@code double} and returns a {@code double} result. This is used
+ * to represent arbitrary mapping functions for converting units to and from a base unit
+ * representation. Temperature units, in particular, typically have an offset from a value in Kelvin
+ * and may have a multiplication factor added in, which means that units cannot always be
+ * represented as simple ratios of their base units.
+ */
 @FunctionalInterface
 public interface UnaryFunction {
   /**

wpiunits/src/main/java/edu/wpi/first/units/UnitBuilder.java

@@ -20,6 +20,12 @@ public final class UnitBuilder<U extends Unit<U>> {
   private String m_name;
   private String m_symbol;
 
+  /**
+   * Creates a new unit builder object, building off of a base unit. The base unit does not have to
+   * be <i>the</i> base unit of its unit system; furlongs work just as well here as meters.
+   *
+   * @param base the unit to base the new unit off of
+   */
   public UnitBuilder(U base) {
     this.m_base = Objects.requireNonNull(base, "Base unit cannot be null");
   }

wpiunits/src/main/java/edu/wpi/first/units/Units.java

@@ -14,91 +14,247 @@ public final class Units {
 
   // Pseudo-classes describing the more common units of measure.
 
+  /**
+   * Used as an internal placeholder value when a specific unit type cannot be determined. Do not
+   * use this directly.
+   */
   @SuppressWarnings("rawtypes")
   public static final Unit AnonymousBaseUnit = new Dimensionless(1, "<?>", "<?>");
 
   // Distance
+  /** The base unit of distance. */
   public static final Distance Meters = BaseUnits.Distance;
+
+  /** 1/1000 of a {@link #Meters Meter}. */
   public static final Distance Millimeters = Milli(Meters, "Millimeter", "mm");
+
+  /** 1/100 of a {@link #Meters Meter}. */
   public static final Distance Centimeters =
       derive(Meters).splitInto(100).named("Centimeter").symbol("cm").make();
+
+  /** 25.4/1000 of a {@link #Meters Meter} and 1/12 of a {@link #Feet Foot}. */
   public static final Distance Inches =
       derive(Millimeters).aggregate(25.4).named("Inch").symbol("in").make();
+
+  /** 304.8/1000 of a {@link #Meters Meter}, or 12 {@link #Inches}. */
   public static final Distance Feet =
       derive(Inches).aggregate(12).named("Foot").symbol("ft").make();
 
   // Time
+  /** The base unit of time. */
   public static final Time Seconds = BaseUnits.Time;
+
+  /** Alias for {@link #Seconds} to make combined unit definitions read more smoothly. */
   public static final Time Second = Seconds; // singularized alias
+
+  /** 1/1000 of a {@link #Seconds Second}. */
   public static final Time Milliseconds = Milli(Seconds);
+
+  /** Alias for {@link #Milliseconds} to make combined unit definitions read more smoothly. */
   public static final Time Millisecond = Milliseconds; // singularized alias
+
+  /** 1/1,000,000 of a {@link #Seconds Second}. */
   public static final Time Microseconds = Micro(Seconds);
+
+  /** Alias for {@link #Microseconds} to make combined unit definitions read more smoothly. */
   public static final Time Microsecond = Microseconds; // singularized alias
+
+  /** 60 {@link #Seconds}. */
   public static final Time Minutes =
       derive(Seconds).aggregate(60).named("Minute").symbol("min").make();
+
+  /** Alias for {@link #Minutes} to make combined unit definitions read more smoothly. */
   public static final Time Minute = Minutes; // singularized alias
 
   // Angle
+  /**
+   * The base SI unit of angle, represented by the distance that the radius of a unit circle can
+   * wrap around its circumference.
+   */
   public static final Angle Radians = BaseUnits.Angle;
+
+  /**
+   * A single turn of an object around an external axis. Numerically equivalent to {@link
+   * #Rotations}, but may be semantically more expressive in certain scenarios.
+   */
   public static final Angle Revolutions = new Angle(2 * Math.PI, "Revolution", "R");
+
+  /**
+   * A single turn of an object around an internal axis. Numerically equivalent to {@link
+   * #Revolutions}, but may be semantically more expressive in certain scenarios.
+   */
   public static final Angle Rotations = new Angle(2 * Math.PI, "Rotation", "R"); // alias revolution
+
+  /** 1/360 of a turn around a circle, or 1/57.3 {@link #Radians}. */
   public static final Angle Degrees =
       derive(Revolutions).splitInto(360).named("Degree").symbol("°").make();
 
   // Velocity
+  /**
+   * The standard SI unit of linear velocity, equivalent to travelling at a rate of one {@link
+   * #Meters Meter} per {@link #Second}.
+   */
   public static final Velocity<Distance> MetersPerSecond = Meters.per(Second);
+
+  /**
+   * A unit of linear velocity equivalent to travelling at a rate one {@link #Feet Foot} per {@link
+   * #Second}.
+   */
   public static final Velocity<Distance> FeetPerSecond = Feet.per(Second);
+
+  /**
+   * A unit of linear velocity equivalent to travelling at a rate of one {@link #Inches Inch} per
+   * {@link #Second}.
+   */
   public static final Velocity<Distance> InchesPerSecond = Inches.per(Second);
 
+  /**
+   * A unit of angular velocity equivalent to spinning at a rate of one {@link #Revolutions
+   * Revolution} per {@link #Second}.
+   */
   public static final Velocity<Angle> RevolutionsPerSecond = Revolutions.per(Second);
+
+  /**
+   * A unit of angular velocity equivalent to spinning at a rate of one {@link #Rotations Rotation}
+   * per {@link #Second}.
+   */
   public static final Velocity<Angle> RotationsPerSecond = Rotations.per(Second);
+
+  /**
+   * A unit of angular velocity equivalent to spinning at a rate of one {@link #Rotations Rotation}
+   * per {@link #Minute}. Motor spec sheets often list maximum speeds in terms of RPM.
+   */
   public static final Velocity<Angle> RPM = Rotations.per(Minute);
+
+  /**
+   * The standard SI unit of angular velocity, equivalent to spinning at a rate of one {@link
+   * #Radians Radian} per {@link #Second}.
+   */
   public static final Velocity<Angle> RadiansPerSecond = Radians.per(Second);
+
+  /**
+   * A unit of angular velocity equivalent to spinning at a rate of one {@link #Degrees Degree} per
+   * {@link #Second}.
+   */
   public static final Velocity<Angle> DegreesPerSecond = Degrees.per(Second);
 
   // Acceleration
+  /**
+   * The standard SI unit of linear acceleration, equivalent to accelerating at a rate of one {@link
+   * #Meters Meter} per {@link #Second} every second.
+   */
   public static final Velocity<Velocity<Distance>> MetersPerSecondPerSecond =
       MetersPerSecond.per(Second);
+
+  /**
+   * A unit of acceleration equivalent to the pull of gravity on an object at sea level on Earth.
+   */
   public static final Velocity<Velocity<Distance>> Gs =
       derive(MetersPerSecondPerSecond).aggregate(9.80665).named("G").symbol("G").make();
 
   // Mass
+  /** The base SI unit of mass. */
   public static final Mass Kilograms = BaseUnits.Mass;
+
+  /** 1/1000 of a {@link #Kilograms Kilogram}. */
   public static final Mass Grams = Milli(Kilograms, "Gram", "g");
+
+  /**
+   * A unit of mass equivalent to approximately 453 {@link #Grams}. This is <i>not</i> equivalent to
+   * pounds-force, which is the amount of force required to accelerate an object with one pound of
+   * mass at a rate of one {@link #Gs G}.
+   */
   public static final Mass Pounds =
       derive(Grams).aggregate(453.592).named("Pound").symbol("lb.").make();
+
+  /** 1/16 of a {@link #Pounds Pound}. */
   public static final Mass Ounces =
       derive(Pounds).splitInto(16).named("Ounce").symbol("oz.").make();
 
   // Unitless
+  /** A dimensionless unit that performs no scaling whatsoever. */
   public static final Dimensionless Value = BaseUnits.Value;
+
+  /**
+   * A dimensionless unit equal to to 1/100th of a {@link #Value}. A measurement of {@code
+   * Percent.of(42)} would be equivalent to {@code Value.of(0.42)}.
+   */
   public static final Dimensionless Percent =
       derive(Value).splitInto(100).named("Percent").symbol("%").make();
 
   // Voltage
+  /** The base unit of electric potential. */
   public static final Voltage Volts = BaseUnits.Voltage;
+
+  /**
+   * 1/1000 of a {@link #Volts Volt}. Useful when dealing with low-voltage applications like LED
+   * drivers or low-power circuits.
+   */
   public static final Voltage Millivolts = Milli(Volts);
 
   // Current
+  /** The base unit of electrical current. */
   public static final Current Amps = BaseUnits.Current;
+
+  /**
+   * A unit equal to 1/1000 of an {@link #Amps Amp}. Useful when dealing with low-current
+   * applications like LED drivers or low-power circuits.
+   */
   public static final Current Milliamps = Milli(Amps);
 
   // Energy
+  /** The base unit of energy. */
   public static final Energy Joules = BaseUnits.Energy;
+
+  /**
+   * A unit equal to 1/1000 of a {@link #Joules Joule}. Useful when dealing with lower-power
+   * applications.
+   */
   public static final Energy Millijoules = Milli(Joules);
+
+  /**
+   * A unit equal to 1,000 {@link #Joules}. Useful when dealing with higher-level robot energy
+   * usage.
+   */
   public static final Energy Kilojoules = Kilo(Joules);
 
   // Power
+  /** The base unit of power. Equivalent to one {@link #Joules Joule} per {@link #Second}. */
   public static final Power Watts = BaseUnits.Power;
+
+  /**
+   * A unit equal to 1/1000 of a {@link #Watts Watt}. Useful when dealing with lower-power
+   * applications.
+   */
   public static final Power Milliwatts = Milli(Watts);
+
+  /**
+   * A unit equal to 745.7 {@link #Watts}. May be useful when dealing with high-power gearboxes and
+   * motors.
+   */
   public static final Power Horsepower =
       derive(Watts).aggregate(745.7).named("Horsepower").symbol("HP").make();
 
   // Temperature
+  /**
+   * The base unit of temperature, where a value of 0 corresponds with absolutely zero energy in the
+   * measured system. Not particularly useful for robots unless you're cooling motors with liquid
+   * helium.
+   */
   public static final Temperature Kelvin = BaseUnits.Temperature;
+
+  /**
+   * The base SI unit of temperature, where a value of 0 roughly corresponds to the freezing point
+   * of water and a value of 100 corresponds to the boiling point. Electronics tend to exhibit
+   * degraded performance or damage above 90 degrees Celsius.
+   */
   public static final Temperature Celsius =
       derive(Kelvin).offset(+273.15).named("Celsius").symbol("°C").make();
 
+  /**
+   * The base imperial (American) unit of temperature, where a value of 32 roughly corresponds to
+   * the freezing point of water and a value of 212 corresponds to the boiling point.
+   */
   public static final Temperature Fahrenheit =
       derive(Celsius)
           .mappingInputRange(0, 100)
@@ -109,13 +265,31 @@ public final class Units {
 
   // Standard feedforward units for kV and kA.
   // kS and kG are just volts, which is already defined earlier
+  /**
+   * A standard unit for measuring linear mechanisms' feedforward voltages based on a model of the
+   * system and a desired commanded linear velocity.
+   */
   public static final Per<Voltage, Velocity<Distance>> VoltsPerMeterPerSecond =
       Volts.per(MetersPerSecond);
+
+  /**
+   * A standard unit for measuring linear mechanisms' feedforward voltages based on a model of the
+   * system and a desired commanded linear acceleration.
+   */
   public static final Per<Voltage, Velocity<Velocity<Distance>>> VoltsPerMeterPerSecondSquared =
       Volts.per(MetersPerSecondPerSecond);
 
+  /**
+   * A standard unit for measuring angular mechanisms' feedforward voltages based on a model of the
+   * system and a desired commanded angular velocity.
+   */
   public static final Per<Voltage, Velocity<Angle>> VoltsPerRadianPerSecond =
       Volts.per(RadiansPerSecond);
+
+  /**
+   * A standard unit for measuring angular mechanisms' feedforward voltages based on a model of the
+   * system and a desired commanded angular acceleration.
+   */
   public static final Per<Voltage, Velocity<Velocity<Angle>>> VoltsPerRadianPerSecondSquared =
       Volts.per(RadiansPerSecond.per(Second));
 
@@ -201,11 +375,26 @@ public final class Units {
         baseUnit, "Kilo" + baseUnit.name().toLowerCase(Locale.ROOT), "K" + baseUnit.symbol());
   }
 
+  /**
+   * Creates a new unit builder object based on a given input unit. The builder can be used to
+   * fluently describe a new unit in terms of its relation to the base unit.
+   *
+   * @param unit the base unit from which to derive a new unit
+   * @param <U> the dimension of the unit to derive
+   * @return a builder object
+   */
   @SuppressWarnings("unchecked")
   public static <U extends Unit<U>> UnitBuilder<U> derive(Unit<U> unit) {
     return new UnitBuilder<>((U) unit);
   }
 
+  /**
+   * Returns an anonymous unit for use when a specific unit type is not known. Do not use this
+   * directly.
+   *
+   * @param <U> the dimension of the desired anonymous unit
+   * @return the anonymous unit
+   */
   @SuppressWarnings("unchecked")
   public static <U extends Unit<U>> U anonymous() {
     return (U) AnonymousBaseUnit;

wpiunits/src/main/java/edu/wpi/first/units/Voltage.java

@@ -23,6 +23,17 @@ public class Voltage extends Unit<Voltage> {
     super(Voltage.class, toBaseConverter, fromBaseConverter, name, symbol);
   }
 
+  /**
+   * Constructs a unit of power equivalent to this unit of voltage multiplied by another unit of
+   * electrical current. For example, {@code Volts.times(Amps)} will return a unit of power
+   * equivalent to one Watt; {@code Volts.times(Milliams)} will return a unit of power equivalent to
+   * a milliwatt, and so on.
+   *
+   * @param current the current unit to multiply by
+   * @param name the name of the resulting unit of power
+   * @param symbol the symbol used to represent the unit of power
+   * @return the power unit
+   */
   public Power times(Unit<Current> current, String name, String symbol) {
     return new Power(toBaseUnits(1) * current.toBaseUnits(1), name, symbol);
   }

wpiunits/src/main/java/edu/wpi/first/units/collections/LongToObjectHashMap.java

@@ -225,8 +225,19 @@ public class LongToObjectHashMap<V> {
     return List.copyOf(values); // return a readonly copy
   }
 
+  /**
+   * Interface for map iterator function.
+   *
+   * @param <V> Value type.
+   */
   @FunctionalInterface
   public interface IteratorFunction<V> {
+    /**
+     * Accepts a key-value pair from the map.
+     *
+     * @param key The key.
+     * @param value The value.
+     */
     void accept(long key, V value);
   }