diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Angle.java b/wpiunits/src/main/java/edu/wpi/first/units/Angle.java index 105a935575..8fd20bb606 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Angle.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Angle.java @@ -4,6 +4,15 @@ package edu.wpi.first.units; +/** + * Unit of angular dimension. + * + *

This is the base type for units of angular dimension. It is also used to specify the dimension + * for {@link Measure}: Measure<Angle>. + * + *

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 is equivalent to (Mass * Distance) / Time - otherwise known // as Power - in other words, Velocity is /actually/ Frequency diff --git a/wpiunits/src/main/java/edu/wpi/first/units/BaseUnits.java b/wpiunits/src/main/java/edu/wpi/first/units/BaseUnits.java index facf02540d..28a36bf79f 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/BaseUnits.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/BaseUnits.java @@ -41,5 +41,6 @@ public final class 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"); } diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Current.java b/wpiunits/src/main/java/edu/wpi/first/units/Current.java index 88418c5106..e1153fd87c 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Current.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Current.java @@ -4,6 +4,15 @@ package edu.wpi.first.units; +/** + * Unit of electic current dimension. + * + *

This is the base type for units of current dimension. It is also used to specify the dimension + * for {@link Measure}: Measure<Current>. + * + *

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(double baseUnitEquivalent, String name, String symbol) { super(Current.class, baseUnitEquivalent, name, symbol); diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Distance.java b/wpiunits/src/main/java/edu/wpi/first/units/Distance.java index d5512ddddd..2e32419141 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Distance.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Distance.java @@ -4,6 +4,15 @@ package edu.wpi.first.units; +/** + * Unit of angular dimension. + * + *

This is the base type for units of distance dimension. It is also used to specify the + * dimension for {@link Measure}: Measure<Distance>. + * + *

Actual units (such as {@link Units#Meters} and {@link Units#Inches}) can be found in the + * {@link Units} class. + */ public class Distance extends Unit { /** Creates a new unit with the given name and multiplier to the base unit. */ Distance(double baseUnitEquivalent, String name, String symbol) { diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Energy.java b/wpiunits/src/main/java/edu/wpi/first/units/Energy.java index d43adf9cd9..d3513d5070 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Energy.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Energy.java @@ -4,6 +4,15 @@ package edu.wpi.first.units; +/** + * Unit of energy dimension. + * + *

This is the base type for units of energy dimension. It is also used to specify the dimension + * for {@link Measure}: Measure<Energy>. + * + *

Actual units (such as {@link Units#Joules} and {@link Units#Kilojoules}) can be found in the + * {@link Units} class. + */ public class Energy extends Unit { protected Energy( UnaryFunction toBaseConverter, UnaryFunction fromBaseConverter, String name, String symbol) { diff --git a/wpiunits/src/main/java/edu/wpi/first/units/ImmutableMeasure.java b/wpiunits/src/main/java/edu/wpi/first/units/ImmutableMeasure.java index 84fb732149..cc7f09f548 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/ImmutableMeasure.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/ImmutableMeasure.java @@ -7,10 +7,10 @@ package edu.wpi.first.units; import java.util.Objects; /** - * A measure holds the magnitude and unit of some dimension, such as distance, time, or speed. A - * measure is immutable and type safe, making it easy to use in concurrent situations - * and gives compile-time safety. Two measures with the same unit and magnitude 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 immutable and type safe, making it easy to use in concurrent + * situations and gives compile-time safety. Two measures with the same unit and + * magnitude are effectively equivalent objects. * * @param the unit type of the measure */ diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Mass.java b/wpiunits/src/main/java/edu/wpi/first/units/Mass.java index c9dc0bbe1e..eb4c45d6c8 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Mass.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Mass.java @@ -4,6 +4,15 @@ package edu.wpi.first.units; +/** + * Unit of mass dimension. + * + *

This is the base type for units of mass dimension. It is also used to specify the dimension + * for {@link Measure}: Measure<Mass>. + * + *

Actual units (such as {@link Units#Grams} and {@link Units#Pounds}) can be found in the {@link + * Units} class. + */ public class Mass extends Unit { /** Creates a new unit with the given name and multiplier to the base unit. */ Mass(double baseUnitEquivalent, String name, String symbol) { 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 908eb2d9a7..c4687b790c 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Measure.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Measure.java @@ -6,7 +6,7 @@ package edu.wpi.first.units; /** * A measure holds the magnitude and unit of some dimension, such as distance, time, or speed. Two - * measures with the same unit and magnitude are effectively the same object. + * measures with the same unit and magnitude are effectively equivalent objects. * * @param the unit type of the measure */ @@ -371,7 +371,7 @@ public interface Measure> extends Comparable> { /** * 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 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 7b6beb32d9..8a0a5fd2de 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Mult.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Mult.java @@ -8,9 +8,7 @@ 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. For example, - * Newton * Meters for torque could be represented as a unit of - * Mult<Force, Distance, Torque> + * A combinatory unit type that is equivalent to the product of two other others. * * @param the type of the first unit in the result * @param the type of the second unit in the result 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 ad035f7390..25ca5ab7e3 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/MutableMeasure.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/MutableMeasure.java @@ -8,13 +8,13 @@ import java.util.Objects; /** * 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. * - *

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

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

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 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 3d8099ffe0..e22b7d6caa 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Per.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Per.java @@ -11,9 +11,7 @@ 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. * - *

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>}, and so on. + *

Note: {@link Velocity} is used to represent the velocity dimension. * * @param the type of the numerator unit * @param the type of the denominator unit diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Power.java b/wpiunits/src/main/java/edu/wpi/first/units/Power.java index cb93c66030..627f1cd874 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Power.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Power.java @@ -4,6 +4,15 @@ package edu.wpi.first.units; +/** + * Unit of power dimension. + * + *

This is the base type for units of power dimension. It is also used to specify the dimension + * for {@link Measure}: Measure<Power>. + * + *

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(double baseUnitEquivalent, String name, String symbol) { super(Power.class, baseUnitEquivalent, name, symbol); diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Temperature.java b/wpiunits/src/main/java/edu/wpi/first/units/Temperature.java index 0a82e4000c..c1f27f4f11 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Temperature.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Temperature.java @@ -4,6 +4,15 @@ package edu.wpi.first.units; +/** + * Unit of temperature dimension. + * + *

This is the base type for units of temperature dimension. It is also used to specify the + * dimension for {@link Measure}: Measure<Temperature>. + * + *

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( UnaryFunction toBaseConverter, UnaryFunction fromBaseConverter, String name, String symbol) { diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Time.java b/wpiunits/src/main/java/edu/wpi/first/units/Time.java index ad91343e54..858ef35236 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Time.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Time.java @@ -4,6 +4,15 @@ package edu.wpi.first.units; +/** + * Unit of time dimension. + * + *

This is the base type for units of time dimension. It is also used to specify the dimension + * for {@link Measure}: Measure<Time>. + * + *

Actual units (such as {@link Units#Seconds} and {@link Units#Milliseconds}) can be found in + * the {@link Units} class. + */ public class Time extends Unit

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 the self type, e.g. {@code class SomeUnit extends Unit} */ 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 a04b54cc08..bf0ebd606b 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Units.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Units.java @@ -6,6 +6,7 @@ package edu.wpi.first.units; import java.util.Locale; +/** Contains a set of predefined units. */ public final class Units { private Units() { // Prevent instantiation 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 87cffb7a45..185c59e625 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Velocity.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Velocity.java @@ -7,6 +7,19 @@ package edu.wpi.first.units; 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). + * + *

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: + * Measure<Velocity<Distance>>. + * + *

Actual units (such as {@link Units#MetersPerSecond} and {@link Units#RPM}) can be found in the + * {@link Units} class. + * + * @param the distance unit, such as {@link Angle} or {@link Distance} + */ public class Velocity> extends Unit> { private final D m_unit; private final Time m_period; diff --git a/wpiunits/src/main/java/edu/wpi/first/units/Voltage.java b/wpiunits/src/main/java/edu/wpi/first/units/Voltage.java index 3c30203410..9006d19866 100644 --- a/wpiunits/src/main/java/edu/wpi/first/units/Voltage.java +++ b/wpiunits/src/main/java/edu/wpi/first/units/Voltage.java @@ -4,6 +4,15 @@ package edu.wpi.first.units; +/** + * Unit of electric voltage dimension. + * + *

This is the base type for units of voltage dimension. It is also used to specify the dimension + * for {@link Measure}: Measure<Voltage>. + * + *

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(double baseUnitEquivalent, String name, String symbol) { super(Voltage.class, baseUnitEquivalent, name, symbol);