[wpiunits] Documentation improvements (wpilibsuite#5932)

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

@@ -4,6 +4,15 @@
 
 package edu.wpi.first.units;
 
+/**
+ * Unit of angular dimension.
+ *
+ * <p>This is the base type for units of angular dimension. It is also used to specify the dimension
+ * for {@link Measure}: <code>Measure&lt;Angle&gt;</code>.
+ *
+ * <p>Actual units (such as {@link Units#Degrees} and {@link Units#Radians}) can be found in the
+ * {@link Units} class.
+ */
 // technically, angles are unitless dimensions
 // eg Mass * Distance * Velocity<Angle> is equivalent to (Mass * Distance) / Time - otherwise known
 // as Power - in other words, Velocity<Angle> is /actually/ Frequency

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

@@ -41,5 +41,6 @@ private BaseUnits() {
   /** The standard unit of power, watts. */
   public static final Power Power = new Power(1, "Watt", "W");
 
+  /** The standard unit of temperature, kelvin. */
   public static final Temperature Temperature = new Temperature(x -> x, x -> x, "Kelvin", "K");
 }

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

@@ -4,6 +4,15 @@
 
 package edu.wpi.first.units;
 
+/**
+ * Unit of electic current dimension.
+ *
+ * <p>This is the base type for units of current dimension. It is also used to specify the dimension
+ * for {@link Measure}: <code>Measure&lt;Current&gt;</code>.
+ *
+ * <p>Actual units (such as {@link Units#Amps} and {@link Units#Milliamps}) can be found in the
+ * {@link Units} class.
+ */
 public class Current extends Unit<Current> {
   Current(double baseUnitEquivalent, String name, String symbol) {
     super(Current.class, baseUnitEquivalent, name, symbol);

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

@@ -4,6 +4,15 @@
 
 package edu.wpi.first.units;
 
+/**
+ * Unit of angular dimension.
+ *
+ * <p>This is the base type for units of distance dimension. It is also used to specify the
+ * dimension for {@link Measure}: <code>Measure&lt;Distance&gt;</code>.
+ *
+ * <p>Actual units (such as {@link Units#Meters} and {@link Units#Inches}) can be found in the
+ * {@link Units} class.
+ */
 public class Distance extends Unit<Distance> {
   /** Creates a new unit with the given name and multiplier to the base unit. */
   Distance(double baseUnitEquivalent, String name, String symbol) {

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

@@ -4,6 +4,15 @@
 
 package edu.wpi.first.units;
 
+/**
+ * Unit of energy dimension.
+ *
+ * <p>This is the base type for units of energy dimension. It is also used to specify the dimension
+ * for {@link Measure}: <code>Measure&lt;Energy&gt;</code>.
+ *
+ * <p>Actual units (such as {@link Units#Joules} and {@link Units#Kilojoules}) can be found in the
+ * {@link Units} class.
+ */
 public class Energy extends Unit<Energy> {
   protected Energy(
       UnaryFunction toBaseConverter, UnaryFunction fromBaseConverter, String name, String symbol) {

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

@@ -7,10 +7,10 @@
 import java.util.Objects;
 
 /**
- * A measure holds the magnitude and unit of some dimension, such as distance, time, or speed. A
- * measure is <i>immutable</i> and <i>type safe</i>, making it easy to use in concurrent situations
- * and gives compile-time safety. Two measures with the same <i>unit</i> and <i>magnitude</i> are
- * effectively the same object.
+ * A measure holds the magnitude and unit of some dimension, such as distance, time, or speed. An
+ * immutable measure is <i>immutable</i> and <i>type safe</i>, making it easy to use in concurrent
+ * situations and gives compile-time safety. Two measures with the same <i>unit</i> and
+ * <i>magnitude</i> are effectively equivalent objects.
  *
  * @param <U> the unit type of the measure
  */

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

@@ -4,6 +4,15 @@
 
 package edu.wpi.first.units;
 
+/**
+ * Unit of mass dimension.
+ *
+ * <p>This is the base type for units of mass dimension. It is also used to specify the dimension
+ * for {@link Measure}: <code>Measure&lt;Mass&gt;</code>.
+ *
+ * <p>Actual units (such as {@link Units#Grams} and {@link Units#Pounds}) can be found in the {@link
+ * Units} class.
+ */
 public class Mass extends Unit<Mass> {
   /** Creates a new unit with the given name and multiplier to the base unit. */
   Mass(double baseUnitEquivalent, String name, String symbol) {

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

@@ -6,7 +6,7 @@
 
 /**
  * A measure holds the magnitude and unit of some dimension, such as distance, time, or speed. Two
- * measures with the same <i>unit</i> and <i>magnitude</i> are effectively the same object.
+ * measures with the same <i>unit</i> and <i>magnitude</i> are effectively equivalent objects.
  *
  * @param <U> the unit type of the measure
  */
@@ -371,7 +371,7 @@ default String toShortString() {
 
   /**
    * Returns a string representation of this measurement in a longhand form. The name of the backing
-   * unit is used, rather than its symbol, and the magnitude is represented in a full string, no
+   * unit is used, rather than its symbol, and the magnitude is represented in a full string, not
    * scientific notation. (Very large values may be represented in scientific notation, however)
    *
    * @return the long form representation of this measurement

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

@@ -8,9 +8,7 @@
 import java.util.Objects;
 
 /**
- * A combinatory unit type that is equivalent to the product of two other others. For example,
- * Newton * Meters for torque could be represented as a unit of <code>
- * Mult&lt;Force, Distance, Torque&gt;</code>
+ * A combinatory unit type that is equivalent to the product of two other others.
  *
  * @param <A> the type of the first unit in the result
  * @param <B> the type of the second unit in the result

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

@@ -8,13 +8,13 @@
 
 /**
  * A specialization of {@link Measure} that allows for mutability. This is intended to be used for
- * memory use reasons (such as on the memory-restricted RoboRIO 1 or 2 or SBC coprocessors) and
+ * memory use reasons (such as on the memory-restricted roboRIO 1 or 2 or SBC coprocessors) and
  * should NOT be exposed in the public API for a class that uses it.
  *
- * <p>The advantage of using this class is that only one instance of a measurement object will exist
- * at a time, as opposed to instantiating a new immutable instance every time a value is fetched.
- * This can greatly reduce memory pressure, but comes at the cost of increased code complexity and
- * sensitivity to race conditions if used poorly.
+ * <p>The advantage of using this class is to reuse one instance of a measurement object, as opposed
+ * to instantiating a new immutable instance every time an operation is performed. This will reduce
+ * memory pressure, but comes at the cost of increased code complexity and sensitivity to race
+ * conditions if misused.
  *
  * <p>Any unsafe methods are prefixed with {@code mut_*}, such as {@link #mut_plus(Measure)} or
  * {@link #mut_replace(Measure)}. These methods will change the internal state of the measurement

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

@@ -11,9 +11,7 @@
  * Generic combinatory unit type that represents the proportion of one unit to another, such as
  * Meters per Second or Radians per Celsius.
  *
- * <p>Note that due to restrictions with the Java type system, velocities (change per unit time) are
- * represented by the {@link Velocity} class. Accelerations are represented by {@code
- * Velocity<Velocity<X>>}, and so on.
+ * <p>Note: {@link Velocity} is used to represent the velocity dimension.
  *
  * @param <N> the type of the numerator unit
  * @param <D> the type of the denominator unit

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

@@ -4,6 +4,15 @@
 
 package edu.wpi.first.units;
 
+/**
+ * Unit of power dimension.
+ *
+ * <p>This is the base type for units of power dimension. It is also used to specify the dimension
+ * for {@link Measure}: <code>Measure&lt;Power&gt;</code>.
+ *
+ * <p>Actual units (such as {@link Units#Watts} and {@link Units#Horsepower}) can be found in the
+ * {@link Units} class.
+ */
 public class Power extends Unit<Power> {
   Power(double baseUnitEquivalent, String name, String symbol) {
     super(Power.class, baseUnitEquivalent, name, symbol);

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

@@ -4,6 +4,15 @@
 
 package edu.wpi.first.units;
 
+/**
+ * Unit of temperature dimension.
+ *
+ * <p>This is the base type for units of temperature dimension. It is also used to specify the
+ * dimension for {@link Measure}: <code>Measure&lt;Temperature&gt;</code>.
+ *
+ * <p>Actual units (such as {@link Units#Celsius} and {@link Units#Fahrenheit}) can be found in the
+ * {@link Units} class.
+ */
 public class Temperature extends Unit<Temperature> {
   Temperature(
       UnaryFunction toBaseConverter, UnaryFunction fromBaseConverter, String name, String symbol) {

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

@@ -4,6 +4,15 @@
 
 package edu.wpi.first.units;
 
+/**
+ * Unit of time dimension.
+ *
+ * <p>This is the base type for units of time dimension. It is also used to specify the dimension
+ * for {@link Measure}: <code>Measure&lt;Time&gt;</code>.
+ *
+ * <p>Actual units (such as {@link Units#Seconds} and {@link Units#Milliseconds}) can be found in
+ * the {@link Units} class.
+ */
 public class Time extends Unit<Time> {
   /** Creates a new unit with the given name and multiplier to the base unit. */
   Time(double baseUnitEquivalent, String name, String symbol) {

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

@@ -7,7 +7,10 @@
 import java.util.Objects;
 
 /**
- * A unit is some unit of measurement that defines a quantity, such as grams, meters, or seconds.
+ * Unit of measurement that defines a quantity, such as grams, meters, or seconds.
+ *
+ * <p>This is the base class for units. Actual units (such as {@link Units#Grams} and {@link
+ * Units#Meters}) can be found in the {@link Units} class.
  *
  * @param <U> the self type, e.g. {@code class SomeUnit extends Unit<SomeUnit>}
  */

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

@@ -6,6 +6,7 @@
 
 import java.util.Locale;
 
+/** Contains a set of predefined units. */
 public final class Units {
   private Units() {
     // Prevent instantiation

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

@@ -7,6 +7,19 @@
 import edu.wpi.first.units.collections.LongToObjectHashMap;
 import java.util.Objects;
 
+/**
+ * Unit of velocity dimension that is a combination of a distance unit (numerator) and a time unit
+ * (denominator).
+ *
+ * <p>This is the base type for units of velocity dimension. It is also used in combination with a
+ * distance dimension to specify the dimension for {@link Measure}. For example: <code>
+ * Measure&lt;Velocity&lt;Distance&gt;&gt;</code>.
+ *
+ * <p>Actual units (such as {@link Units#MetersPerSecond} and {@link Units#RPM}) can be found in the
+ * {@link Units} class.
+ *
+ * @param <D> the distance unit, such as {@link Angle} or {@link Distance}
+ */
 public class Velocity<D extends Unit<D>> extends Unit<Velocity<D>> {
   private final D m_unit;
   private final Time m_period;

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

@@ -4,6 +4,15 @@
 
 package edu.wpi.first.units;
 
+/**
+ * Unit of electric voltage dimension.
+ *
+ * <p>This is the base type for units of voltage dimension. It is also used to specify the dimension
+ * for {@link Measure}: <code>Measure&lt;Voltage&gt;</code>.
+ *
+ * <p>Actual units (such as {@link Units#Volts} and {@link Units#Millivolts}) can be found in the
+ * {@link Units} class.
+ */
 public class Voltage extends Unit<Voltage> {
   Voltage(double baseUnitEquivalent, String name, String symbol) {
     super(Voltage.class, baseUnitEquivalent, name, symbol);