diff --git a/docs/build.gradle b/docs/build.gradle index 3762cf4f9d..1a1e3b10e0 100644 --- a/docs/build.gradle +++ b/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' diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Measure.java b/wpiunits/src/main/java/edu/wpi/first/units/Measure.java index 2decf37cfc..908eb2d9a7 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Measure.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Measure.java @@ -17,13 +17,26 @@ public interface Measure> extends Comparable> { */ 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> extends Comparable> { * seconds. Converting to the same unit is equivalent to calling {@link #magnitude()}. * *
-   *   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
    * 
* * @param unit the unit to convert this measure to @@ -47,9 +60,13 @@ public interface Measure> extends Comparable> { } /** - * 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 base 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 in terms of the base unit. * * @param multiplier the constant to multiply by + * @return the resulting measure */ default Measure times(double multiplier) { return ImmutableMeasure.ofBaseUnits(baseUnitMagnitude() * multiplier, unit()); @@ -110,6 +127,7 @@ public interface Measure> extends Comparable> { * {@code times(1 / divisor)} * * @param divisor the constant to divide by + * @return the resulting measure * @see #times(double) */ default Measure divide(double divisor) { @@ -121,6 +139,7 @@ public interface Measure> extends Comparable> { * {@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> extends Comparable> { * Creates a velocity measure by dividing this one by a time period measure. * *
-   *   Meters.of(1).per(Second) // => Measure<Velocity<Distance>>
+   *   Meters.of(1).per(Second) // Measure<Velocity<Distance>>
    * 
* * @param period the time period to divide by. @@ -147,7 +166,7 @@ public interface Measure> extends Comparable> { * Creates a relational measure equivalent to this one per some other unit. * *
-   *   Volts.of(1.05).per(Meter) // => V/m, potential PID constant
+   *   Volts.of(1.05).per(Meter) // V/m, potential PID constant
    * 
* * @param the type of the denominator unit @@ -179,7 +198,11 @@ public interface Measure> extends Comparable> { 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 negate() { return times(-1); } @@ -187,6 +210,8 @@ public interface Measure> extends Comparable> { /** * Returns an immutable copy of this measure. The copy can be used freely and is guaranteed never * to change. + * + * @return the copied measure */ Measure copy(); @@ -204,8 +229,8 @@ public interface Measure> extends Comparable> { * for use for a +/- scalar, such as 0.05 for +/- 5%. * *
-   *   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
    * 
* * @param other the other measurement to compare against @@ -240,6 +265,7 @@ public interface Measure> extends Comparable> { return Math.abs(baseUnitMagnitude() - other.baseUnitMagnitude()) <= EQUIVALENCE_THRESHOLD; } + /** {@inheritDoc} */ @Override default int compareTo(Measure o) { return Double.compare(this.baseUnitMagnitude(), o.baseUnitMagnitude()); @@ -249,6 +275,7 @@ public interface Measure> extends Comparable> { * 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 o) { return compareTo(o) > 0; @@ -258,6 +285,7 @@ public interface Measure> extends Comparable> { * 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 o) { return compareTo(o) > 0 || isEquivalent(o); @@ -267,6 +295,7 @@ public interface Measure> extends Comparable> { * 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 o) { return compareTo(o) < 0; @@ -276,6 +305,7 @@ public interface Measure> extends Comparable> { * 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 o) { return compareTo(o) < 0 || isEquivalent(o); diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Mult.java b/wpiunits/src/main/java/edu/wpi/first/units/Mult.java index c1640875c3..7b6beb32d9 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Mult.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Mult.java @@ -36,7 +36,7 @@ public class Mult, B extends Unit> extends Unit> * Creates a new Mult unit derived from two arbitrary units multiplied together. * *
-   *   Mult.combine(Volts, Meters) // => Volt-Meters
+   *   Mult.combine(Volts, Meters) // Volt-Meters
    * 
* *

It's recommended to use the convenience function {@link Unit#mult(Unit)} instead of calling diff --git a/wpiunits/src/main/java/edu/wpi/first/units/MutableMeasure.java b/wpiunits/src/main/java/edu/wpi/first/units/MutableMeasure.java index fad45f0dd7..ad035f7390 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/MutableMeasure.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/MutableMeasure.java @@ -221,6 +221,7 @@ public final class MutableMeasure> implements Measure { * 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 mut_minus(double magnitude, U unit) { diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Per.java b/wpiunits/src/main/java/edu/wpi/first/units/Per.java index 8f0bac0950..3d8099ffe0 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Per.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Per.java @@ -44,7 +44,7 @@ public class Per, D extends Unit> extends Unit> { * denominator with a unit of time is discouraged; use {@link Velocity} instead. * *

-   *   Per.combine(Volts, Meters) // => possible PID constant
+   *   Per.combine(Volts, Meters) // possible PID constant
    * 
* *

It's recommended to use the convenience function {@link Unit#per(Unit)} instead of calling diff --git a/wpiunits/src/main/java/edu/wpi/first/units/UnaryFunction.java b/wpiunits/src/main/java/edu/wpi/first/units/UnaryFunction.java index 7148631d79..ca5c8a2f7f 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/UnaryFunction.java +++ b/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. * *

-   * f = x -> x + 1 // f(x) = x + 1
-   * g = x -> 2 * x // g(x) = 2x
+   * f = x -> x + 1 // f(x) = x + 1
+   * g = x -> 2 * x // g(x) = 2x
    *
    * h = f.pipeTo(g) // h(x) = g(f(x))
    * 
* * @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); } diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Unit.java b/wpiunits/src/main/java/edu/wpi/first/units/Unit.java index 988f902441..df960ea337 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Unit.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Unit.java @@ -85,12 +85,13 @@ public class Unit> { * this unit. * *
-   *   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
    * 
* * @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 otherUnit) { if (this.equivalent(otherUnit)) { @@ -125,6 +126,7 @@ public class Unit> { * immutable and cannot have its value modified. * * @param magnitude the magnitude of the measure to create + * @return the measure */ public Measure of(double magnitude) { if (magnitude == 0) { @@ -180,8 +182,8 @@ public class Unit> { * jerk, etc. * *
-   *   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
    * 
* diff --git a/wpiunits/src/main/java/edu/wpi/first/units/UnitBuilder.java b/wpiunits/src/main/java/edu/wpi/first/units/UnitBuilder.java index 966b60187e..b8dc0b9a6d 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/UnitBuilder.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/UnitBuilder.java @@ -29,6 +29,7 @@ public final class UnitBuilder> { * (base value - offset). * * @param offset the offset + * @return this builder */ public UnitBuilder offset(double offset) { m_toBase = derivedValue -> derivedValue + offset; diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Units.java b/wpiunits/src/main/java/edu/wpi/first/units/Units.java index 43e5369913..ecf0768a18 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Units.java +++ b/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 Milli(Unit baseUnit, String name, String symbol) { @@ -137,6 +138,7 @@ public final class Units { * * @param 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 Milli(Unit 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 Micro(Unit baseUnit, String name, String symbol) { @@ -163,6 +166,7 @@ public final class Units { * * @param 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 Micro(Unit 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 Kilo(Unit baseUnit, String name, String symbol) { @@ -188,6 +193,7 @@ public final class Units { * * @param 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 Kilo(Unit baseUnit) { diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Velocity.java b/wpiunits/src/main/java/edu/wpi/first/units/Velocity.java index 1fd828c844..87cffb7a45 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Velocity.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Velocity.java @@ -30,12 +30,12 @@ public class Velocity> extends Unit> { * the pre-existing units instead of generating new identical ones. * *
-   *   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
    * 
* *

It's recommended to use the convenience function {@link Unit#per(Time)} instead of calling @@ -70,12 +70,12 @@ public class Velocity> extends Unit> { *

This method automatically generates a new name and symbol for the new velocity unit. * *

-   *   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
    * 
* *

It's recommended to use the convenience function {@link Unit#per(Time)} instead of calling diff --git a/wpiunits/src/main/java/edu/wpi/first/units/collections/ReadOnlyPrimitiveLongSet.java b/wpiunits/src/main/java/edu/wpi/first/units/collections/ReadOnlyPrimitiveLongSet.java index 5780b88e18..0b13824ec3 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/collections/ReadOnlyPrimitiveLongSet.java +++ b/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 { 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); }