[docs] Add wpiunits to JavaDocs (#5793)

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

docs/build.gradle

@@ -235,6 +235,7 @@ task generateJavaDocs(type: Javadoc) {
     source project(':wpilibj').sourceSets.main.java
     source project(':wpimath').sourceSets.main.java
     source project(':wpinet').sourceSets.main.java
+    source project(':wpiunits').sourceSets.main.java
     source project(':wpiutil').sourceSets.main.java
     source configurations.javaSource.collect { zipTree(it) }
     include '**/*.java'

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

@@ -17,13 +17,26 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
    */
   double EQUIVALENCE_THRESHOLD = 1e-12;
 
-  /** Gets the unitless magnitude of this measure. */
+  /**
+   * Gets the unitless magnitude of this measure.
+   *
+   * @return the magnitude in terms of {@link #unit() the unit}.
+   */
   double magnitude();
 
-  /** Gets the magnitude of this measure in terms of the base unit. */
+  /**
+   * Gets the magnitude of this measure in terms of the base unit. If the unit is the base unit for
+   * its system of measure, then the value will be equivalent to {@link #magnitude()}.
+   *
+   * @return the magnitude in terms of the base unit
+   */
   double baseUnitMagnitude();
 
-  /** Gets the units of this measure. */
+  /**
+   * Gets the units of this measure.
+   *
+   * @return the unit
+   */
   U unit();
 
   /**
@@ -31,8 +44,8 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
    * seconds. Converting to the same unit is equivalent to calling {@link #magnitude()}.
    *
    * <pre>
-   *   Meters.of(12).in(Feet) // => 39.3701
-   *   Seconds.of(15).in(Minutes) // => 0.25
+   *   Meters.of(12).in(Feet) // 39.3701
+   *   Seconds.of(15).in(Minutes) // 0.25
    * </pre>
    *
    * @param unit the unit to convert this measure to
@@ -47,9 +60,13 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
   }
 
   /**
-   * Multiplies this measurement by some constant multiplier and returns the result.
+   * Multiplies this measurement by some constant multiplier and returns the result. The magnitude
+   * of the result will be the <i>base</i> magnitude multiplied by the scalar value. If the measure
+   * uses a unit with a non-linear relation to its base unit (such as Fahrenheit for temperature),
+   * then the result will only be a multiple <i>in terms of the base unit</i>.
    *
    * @param multiplier the constant to multiply by
+   * @return the resulting measure
    */
   default Measure<U> times(double multiplier) {
     return ImmutableMeasure.ofBaseUnits(baseUnitMagnitude() * multiplier, unit());
@@ -110,6 +127,7 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
    * {@code times(1 / divisor)}
    *
    * @param divisor the constant to divide by
+   * @return the resulting measure
    * @see #times(double)
    */
   default Measure<U> divide(double divisor) {
@@ -121,6 +139,7 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
    * {@code divide(divisor.baseUnitMagnitude())}
    *
    * @param divisor the dimensionless measure to divide by
+   * @return the resulting measure
    * @see #divide(double)
    * @see #times(double)
    */
@@ -132,7 +151,7 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
    * Creates a velocity measure by dividing this one by a time period measure.
    *
    * <pre>
-   *   Meters.of(1).per(Second) // => Measure&lt;Velocity&lt;Distance&gt;&gt;
+   *   Meters.of(1).per(Second) // Measure&lt;Velocity&lt;Distance&gt;&gt;
    * </pre>
    *
    * @param period the time period to divide by.
@@ -147,7 +166,7 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
    * Creates a relational measure equivalent to this one per some other unit.
    *
    * <pre>
-   *   Volts.of(1.05).per(Meter) // => V/m, potential PID constant
+   *   Volts.of(1.05).per(Meter) // V/m, potential PID constant
    * </pre>
    *
    * @param <U2> the type of the denominator unit
@@ -179,7 +198,11 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
     return unit().ofBaseUnits(baseUnitMagnitude() - other.baseUnitMagnitude());
   }
 
-  /** Negates this measure and returns the result. */
+  /**
+   * Negates this measure and returns the result.
+   *
+   * @return the resulting measure
+   */
   default Measure<U> negate() {
     return times(-1);
   }
@@ -187,6 +210,8 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
   /**
    * Returns an immutable copy of this measure. The copy can be used freely and is guaranteed never
    * to change.
+   *
+   * @return the copied measure
    */
   Measure<U> copy();
 
@@ -204,8 +229,8 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
    * for use for a +/- scalar, such as 0.05 for +/- 5%.
    *
    * <pre>
-   *   Inches.of(11).isNear(Inches.of(10), 0.1) // => true
-   *   Inches.of(12).isNear(Inches.of(10), 0.1) // => false
+   *   Inches.of(11).isNear(Inches.of(10), 0.1) // true
+   *   Inches.of(12).isNear(Inches.of(10), 0.1) // false
    * </pre>
    *
    * @param other the other measurement to compare against
@@ -240,6 +265,7 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
     return Math.abs(baseUnitMagnitude() - other.baseUnitMagnitude()) <= EQUIVALENCE_THRESHOLD;
   }
 
+  /** {@inheritDoc} */
   @Override
   default int compareTo(Measure<U> o) {
     return Double.compare(this.baseUnitMagnitude(), o.baseUnitMagnitude());
@@ -249,6 +275,7 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
    * Checks if this measure is greater than another measure of the same unit.
    *
    * @param o the other measure to compare to
+   * @return true if this measure has a greater equivalent magnitude, false otherwise
    */
   default boolean gt(Measure<U> o) {
     return compareTo(o) > 0;
@@ -258,6 +285,7 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
    * Checks if this measure is greater than or equivalent to another measure of the same unit.
    *
    * @param o the other measure to compare to
+   * @return true if this measure has an equal or greater equivalent magnitude, false otherwise
    */
   default boolean gte(Measure<U> o) {
     return compareTo(o) > 0 || isEquivalent(o);
@@ -267,6 +295,7 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
    * Checks if this measure is less than another measure of the same unit.
    *
    * @param o the other measure to compare to
+   * @return true if this measure has a lesser equivalent magnitude, false otherwise
    */
   default boolean lt(Measure<U> o) {
     return compareTo(o) < 0;
@@ -276,6 +305,7 @@ public interface Measure<U extends Unit<U>> extends Comparable<Measure<U>> {
    * Checks if this measure is less than or equivalent to another measure of the same unit.
    *
    * @param o the other measure to compare to
+   * @return true if this measure has an equal or lesser equivalent magnitude, false otherwise
    */
   default boolean lte(Measure<U> o) {
     return compareTo(o) < 0 || isEquivalent(o);

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

@@ -36,7 +36,7 @@ public class Mult<A extends Unit<A>, B extends Unit<B>> extends Unit<Mult<A, B>>
    * Creates a new Mult unit derived from two arbitrary units multiplied together.
    *
    * <pre>
-   *   Mult.combine(Volts, Meters) // => Volt-Meters
+   *   Mult.combine(Volts, Meters) // Volt-Meters
    * </pre>
    *
    * <p>It's recommended to use the convenience function {@link Unit#mult(Unit)} instead of calling

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

@@ -221,6 +221,7 @@ public final class MutableMeasure<U extends Unit<U>> implements Measure<U> {
    * having to wrap raw numbers in a {@code Measure} object and pay for an object allocation.
    *
    * @param magnitude the magnitude of the other measurement.
+   * @param unit the unit of the other measurement
    * @return this measure
    */
   public MutableMeasure<U> mut_minus(double magnitude, U unit) {

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

@@ -44,7 +44,7 @@ public class Per<N extends Unit<N>, D extends Unit<D>> extends Unit<Per<N, D>> {
    * denominator with a unit of time is discouraged; use {@link Velocity} instead.
    *
    * <pre>
-   *   Per.combine(Volts, Meters) // => possible PID constant
+   *   Per.combine(Volts, Meters) // possible PID constant
    * </pre>
    *
    * <p>It's recommended to use the convenience function {@link Unit#per(Unit)} instead of calling

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

@@ -8,6 +8,12 @@ import java.util.Objects;
 
 @FunctionalInterface
 public interface UnaryFunction {
+  /**
+   * Applies this function to the input value and returns the result.
+   *
+   * @param input the input value to the function
+   * @return the result
+   */
   double apply(double input);
 
   /**
@@ -15,13 +21,14 @@ public interface UnaryFunction {
    * input.
    *
    * <pre>
-   * f = x -> x + 1 // f(x) = x + 1
-   * g = x -> 2 * x // g(x) = 2x
+   * f = x -&gt; x + 1 // f(x) = x + 1
+   * g = x -&gt; 2 * x // g(x) = 2x
    *
    * h = f.pipeTo(g) // h(x) = g(f(x))
    * </pre>
    *
    * @param next the next operation to pipe to
+   * @return the composite function g(f(x))
    */
   default UnaryFunction pipeTo(UnaryFunction next) {
     Objects.requireNonNull(next, "The next operation in the chain must be provided");
@@ -29,19 +36,34 @@ public interface UnaryFunction {
     return x -> next.apply(this.apply(x));
   }
 
-  /** h(x) = f(x) * g(x). */
+  /**
+   * Creates a composite function h(x) such that h(x) = f(x) * g(x).
+   *
+   * @param multiplier the function to multiply this one by
+   * @return the composite function f(x) * g(x)
+   */
   default UnaryFunction mult(UnaryFunction multiplier) {
     Objects.requireNonNull(multiplier, "A multiplier function must be provided");
 
     return x -> this.apply(x) * multiplier.apply(x);
   }
 
-  /** g(x) = f(x) * k. */
+  /**
+   * Creates a composite function h(x) such that h(x) = k * f(x).
+   *
+   * @param multiplier the constant value to multiply this function's results by
+   * @return the composite function k * f(x)
+   */
   default UnaryFunction mult(double multiplier) {
     return x -> this.apply(x) * multiplier;
   }
 
-  /** h(x) = f(x) / g(x). */
+  /**
+   * Creates a composite function h(x) such that h(x) = f(x) / g(x).
+   *
+   * @param divisor the function to divide this one by
+   * @return the composite function f(x) / g(x)
+   */
   default UnaryFunction div(UnaryFunction divisor) {
     Objects.requireNonNull(divisor, "A divisor function must be provided");
 
@@ -59,18 +81,34 @@ public interface UnaryFunction {
     };
   }
 
-  /** g(x) * f(x) / k. */
+  /**
+   * Creates a composite function h(x) such that h(x) = 1/k * f(x).
+   *
+   * @param divisor the constant value to divide this function's results by
+   * @return the composite function 1/k * f(x)
+   */
   default UnaryFunction div(double divisor) {
     return x -> this.apply(x) / divisor;
   }
 
-  /** h(x) = f(x) ^ g(x). */
+  /**
+   * Creates a composite function h(x) such that h(x) = f(x) ^ g(x).
+   *
+   * @param exponent the function to exponentiate this function's results by
+   * @return the composite function f(x) ^ g(x)
+   */
   default UnaryFunction exp(UnaryFunction exponent) {
     Objects.requireNonNull(exponent, "An exponent function must be provided");
 
     return x -> Math.pow(this.apply(x), exponent.apply(x));
   }
 
+  /**
+   * Creates a composite function h(x) such that h(x) = f(x) ^ k.
+   *
+   * @param exponent the constant value to exponentiate this function's results by
+   * @return the composite function f(x) ^ k
+   */
   default UnaryFunction exp(double exponent) {
     return x -> Math.pow(this.apply(x), exponent);
   }

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

@@ -85,12 +85,13 @@ public class Unit<U extends Unit<U>> {
    * this unit.
    *
    * <pre>
-   *   Inches.convertFrom(12, Feet) // => 144.0
-   *   Kilograms.convertFrom(2.2, Pounds) // => 0.9979024
+   *   Inches.convertFrom(12, Feet) // 144.0
+   *   Kilograms.convertFrom(2.2, Pounds) // 0.9979024
    * </pre>
    *
    * @param magnitude a magnitude measured in another unit
    * @param otherUnit the unit to convert the magnitude to
+   * @return the corresponding value in terms of this unit.
    */
   public double convertFrom(double magnitude, Unit<U> otherUnit) {
     if (this.equivalent(otherUnit)) {
@@ -125,6 +126,7 @@ public class Unit<U extends Unit<U>> {
    * <i>immutable</i> and cannot have its value modified.
    *
    * @param magnitude the magnitude of the measure to create
+   * @return the measure
    */
   public Measure<U> of(double magnitude) {
     if (magnitude == 0) {
@@ -180,8 +182,8 @@ public class Unit<U extends Unit<U>> {
    * jerk, etc.
    *
    * <pre>
-   *   Meters.per(Second) // => linear velocity
-   *   Kilograms.per(Second) // => mass flow
+   *   Meters.per(Second) // linear velocity
+   *   Kilograms.per(Second) // mass flow
    *   Feet.per(Second).per(Second).of(32) // roughly 1G of acceleration
    * </pre>
    *

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

@@ -29,6 +29,7 @@ public final class UnitBuilder<U extends Unit<U>> {
    * (base value - offset).
    *
    * @param offset the offset
+   * @return this builder
    */
   public UnitBuilder<U> offset(double offset) {
     m_toBase = derivedValue -> derivedValue + offset;

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

@@ -126,6 +126,7 @@ public final class Units {
    * @param baseUnit the unit being derived from. This does not have to be the base unit of measure
    * @param name the name of the new derived unit
    * @param symbol the symbol of the new derived unit
+   * @return the milli-unit
    */
   @SuppressWarnings({"PMD.MethodName", "checkstyle:methodname"})
   public static <U extends Unit<U>> U Milli(Unit<U> baseUnit, String name, String symbol) {
@@ -137,6 +138,7 @@ public final class Units {
    *
    * @param <U> the type of the unit
    * @param baseUnit the unit being derived from. This does not have to be the base unit of measure
+   * @return the milli-unit
    */
   @SuppressWarnings({"PMD.MethodName", "checkstyle:methodname"})
   public static <U extends Unit<U>> U Milli(Unit<U> baseUnit) {
@@ -152,6 +154,7 @@ public final class Units {
    * @param baseUnit the unit being derived from. This does not have to be the base unit of measure
    * @param name the name of the new derived unit
    * @param symbol the symbol of the new derived unit
+   * @return the micro-unit
    */
   @SuppressWarnings({"PMD.MethodName", "checkstyle:methodname"})
   public static <U extends Unit<U>> U Micro(Unit<U> baseUnit, String name, String symbol) {
@@ -163,6 +166,7 @@ public final class Units {
    *
    * @param <U> the type of the unit
    * @param baseUnit the unit being derived from. This does not have to be the base unit of measure
+   * @return the micro-unit
    */
   @SuppressWarnings({"PMD.MethodName", "checkstyle:methodname"})
   public static <U extends Unit<U>> U Micro(Unit<U> baseUnit) {
@@ -177,6 +181,7 @@ public final class Units {
    * @param baseUnit the unit being derived from. This does not have to be the base unit of measure
    * @param name the name of the new derived unit
    * @param symbol the symbol of the new derived unit
+   * @return the kilo-unit
    */
   @SuppressWarnings({"PMD.MethodName", "checkstyle:methodname"})
   public static <U extends Unit<U>> U Kilo(Unit<U> baseUnit, String name, String symbol) {
@@ -188,6 +193,7 @@ public final class Units {
    *
    * @param <U> the type of the unit
    * @param baseUnit the unit being derived from. This does not have to be the base unit of measure
+   * @return the kilo-unit
    */
   @SuppressWarnings({"PMD.MethodName", "checkstyle:methodname"})
   public static <U extends Unit<U>> U Kilo(Unit<U> baseUnit) {

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

@@ -30,12 +30,12 @@ public class Velocity<D extends Unit<D>> extends Unit<Velocity<D>> {
    * the pre-existing units instead of generating new identical ones.
    *
    * <pre>
-   *   Velocity.combine(Kilograms, Second) // => mass flow
-   *   Velocity.combine(Feet, Millisecond) // => linear speed
-   *   Velocity.combine(Radians, Second) // => angular speed
+   *   Velocity.combine(Kilograms, Second) // mass flow
+   *   Velocity.combine(Feet, Millisecond) // linear speed
+   *   Velocity.combine(Radians, Second) // angular speed
    *
-   *   Velocity.combine(Feet.per(Second), Second) // => linear acceleration in ft/s/s
-   *   Velocity.combine(Radians.per(Second), Second) // => angular acceleration
+   *   Velocity.combine(Feet.per(Second), Second) // linear acceleration in ft/s/s
+   *   Velocity.combine(Radians.per(Second), Second) // angular acceleration
    * </pre>
    *
    * <p>It's recommended to use the convenience function {@link Unit#per(Time)} instead of calling
@@ -70,12 +70,12 @@ public class Velocity<D extends Unit<D>> extends Unit<Velocity<D>> {
    * <p>This method automatically generates a new name and symbol for the new velocity unit.
    *
    * <pre>
-   *   Velocity.combine(Kilograms, Second) // => mass flow
-   *   Velocity.combine(Feet, Millisecond) // => linear speed
-   *   Velocity.combine(Radians, Second) // => angular speed
+   *   Velocity.combine(Kilograms, Second) // mass flow
+   *   Velocity.combine(Feet, Millisecond) // linear speed
+   *   Velocity.combine(Radians, Second) // angular speed
    *
-   *   Velocity.combine(Feet.per(Second), Second) // => linear acceleration in ft/s/s
-   *   Velocity.combine(Radians.per(Second), Second) // => angular acceleration
+   *   Velocity.combine(Feet.per(Second), Second) // linear acceleration in ft/s/s
+   *   Velocity.combine(Radians.per(Second), Second) // angular acceleration
    * </pre>
    *
    * <p>It's recommended to use the convenience function {@link Unit#per(Time)} instead of calling

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

@@ -7,6 +7,7 @@ package edu.wpi.first.units.collections;
 import java.util.Arrays;
 import java.util.Iterator;
 import java.util.NoSuchElementException;
+import java.util.Set;
 import java.util.stream.LongStream;
 
 /** A read-only set of unique primitive {@code long} values. */
@@ -87,7 +88,12 @@ public class ReadOnlyPrimitiveLongSet implements Iterable<Long> {
     return size() == 0;
   }
 
-  /** Creates a stream of primitive long values for the set. */
+  /**
+   * Creates a stream of primitive long values for the set.
+   *
+   * @return a sequential Stream over the elements in this collection
+   * @see Set#stream()
+   */
   public LongStream stream() {
     return Arrays.stream(m_values);
   }