From 161dfefb4d02020b56c1f205661866a4ae0d95a7 Mon Sep 17 00:00:00 2001 From: Ryan Blue Date: Sun, 8 Sep 2024 01:21:16 -0400 Subject: [PATCH] [docs] Add romi and xrp to docs build (#7045) --- docs/build.gradle | 6 +++ .../edu/wpi/first/wpilibj/romi/OnBoardIO.java | 3 ++ .../edu/wpi/first/wpilibj/romi/RomiGyro.java | 23 +++++++++++ .../main/native/include/frc/romi/OnBoardIO.h | 10 ++++- .../main/native/include/frc/romi/RomiGyro.h | 7 ++++ .../main/native/include/frc/romi/RomiMotor.h | 7 ++++ .../edu/wpi/first/wpilibj/xrp/XRPGyro.java | 6 ++- .../edu/wpi/first/wpilibj/xrp/XRPMotor.java | 6 ++- .../wpi/first/wpilibj/xrp/XRPRangefinder.java | 7 ++++ .../wpilibj/xrp/XRPReflectanceSensor.java | 7 ++++ .../edu/wpi/first/wpilibj/xrp/XRPServo.java | 34 +++++++++-------- .../src/main/native/include/frc/xrp/XRPGyro.h | 12 ++++++ .../main/native/include/frc/xrp/XRPMotor.h | 12 ++++++ .../native/include/frc/xrp/XRPOnBoardIO.h | 7 ++++ .../native/include/frc/xrp/XRPRangefinder.h | 7 ++++ .../include/frc/xrp/XRPReflectanceSensor.h | 7 ++++ .../main/native/include/frc/xrp/XRPServo.h | 38 +++++++++++++++++++ 17 files changed, 181 insertions(+), 18 deletions(-) diff --git a/docs/build.gradle b/docs/build.gradle index d3bb3dc3ad..fc460dea26 100644 --- a/docs/build.gradle +++ b/docs/build.gradle @@ -16,6 +16,8 @@ evaluationDependsOn(':wpimath') evaluationDependsOn(':wpinet') evaluationDependsOn(':wpiunits') evaluationDependsOn(':wpiutil') +evaluationDependsOn(':romiVendordep') +evaluationDependsOn(':xrpVendordep') def baseArtifactIdCpp = 'documentation' def artifactGroupIdCpp = 'edu.wpi.first.wpilibc' @@ -40,6 +42,8 @@ cppProjectZips.add(project(':wpilibc').cppHeadersZip) cppProjectZips.add(project(':wpimath').cppHeadersZip) cppProjectZips.add(project(':wpinet').cppHeadersZip) cppProjectZips.add(project(':wpiutil').cppHeadersZip) +cppProjectZips.add(project(':romiVendordep').cppHeadersZip) +cppProjectZips.add(project(':xrpVendordep').cppHeadersZip) doxygen { // Doxygen binaries are only provided for x86_64 platforms @@ -224,6 +228,8 @@ task generateJavaDocs(type: Javadoc) { source project(':wpinet').sourceSets.main.java source project(':wpiunits').sourceSets.main.java source project(':wpiutil').sourceSets.main.java + source project(':romiVendordep').sourceSets.main.java + source project(':xrpVendordep').sourceSets.main.java source configurations.javaSource.collect { zipTree(it) } include '**/*.java' failOnError = true diff --git a/romiVendordep/src/main/java/edu/wpi/first/wpilibj/romi/OnBoardIO.java b/romiVendordep/src/main/java/edu/wpi/first/wpilibj/romi/OnBoardIO.java index 02dcc2a137..40bbead462 100644 --- a/romiVendordep/src/main/java/edu/wpi/first/wpilibj/romi/OnBoardIO.java +++ b/romiVendordep/src/main/java/edu/wpi/first/wpilibj/romi/OnBoardIO.java @@ -31,8 +31,11 @@ public class OnBoardIO { private static final double MESSAGE_INTERVAL = 1.0; private double m_nextMessageTime; + /** Mode for Romi onboard IO channel. */ public enum ChannelMode { + /** Input. */ INPUT, + /** Output. */ OUTPUT } diff --git a/romiVendordep/src/main/java/edu/wpi/first/wpilibj/romi/RomiGyro.java b/romiVendordep/src/main/java/edu/wpi/first/wpilibj/romi/RomiGyro.java index 40eaefc20b..439c2402ad 100644 --- a/romiVendordep/src/main/java/edu/wpi/first/wpilibj/romi/RomiGyro.java +++ b/romiVendordep/src/main/java/edu/wpi/first/wpilibj/romi/RomiGyro.java @@ -8,6 +8,12 @@ import edu.wpi.first.hal.SimDevice; import edu.wpi.first.hal.SimDevice.Direction; import edu.wpi.first.hal.SimDouble; +/** + * Use a rate gyro to return the robots heading relative to a starting position. + * + *

This class is for the Romi onboard gyro, and will only work in simulation/Romi mode. Only one + * instance of a RomiGyro is supported. + */ public class RomiGyro { private final SimDevice m_simDevice; private final SimDouble m_simRateX; @@ -130,10 +136,27 @@ public class RomiGyro { } } + /** + * Return the actual angle in degrees that the robot is currently facing. + * + *

The angle is based on integration of the returned rate form the gyro. The angle is + * continuous, that is, it will continue from 360->361 degrees. This allows algorithms that + * wouldn't want to see a discontinuity in the gyro output as it sweeps from 360 to 0 on the + * second time around. + * + * @return the current heading of the robot in degrees. + */ public double getAngle() { return getAngleZ(); } + /** + * Return the rate of rotation of the gyro + * + *

The rate is based on the most recent reading of the gyro. + * + * @return the current rate in degrees per second + */ public double getRate() { return getRateZ(); } diff --git a/romiVendordep/src/main/native/include/frc/romi/OnBoardIO.h b/romiVendordep/src/main/native/include/frc/romi/OnBoardIO.h index 8e08a35c71..eef6a8488d 100644 --- a/romiVendordep/src/main/native/include/frc/romi/OnBoardIO.h +++ b/romiVendordep/src/main/native/include/frc/romi/OnBoardIO.h @@ -12,6 +12,11 @@ namespace frc { +/** + * @ingroup romi_api + * @{ + */ + /** * This class represents the onboard IO of the Romi * reference robot. This includes the pushbuttons and @@ -24,7 +29,8 @@ namespace frc { */ class OnBoardIO { public: - enum ChannelMode { INPUT, OUTPUT }; + /** Mode for Romi onboard IO */ + enum ChannelMode { /** Input */ INPUT, /** Output */ OUTPUT }; OnBoardIO(OnBoardIO::ChannelMode dio1, OnBoardIO::ChannelMode dio2); static constexpr auto kMessageInterval = 1_s; @@ -73,4 +79,6 @@ class OnBoardIO { std::unique_ptr m_redLed; }; +/** @} */ + } // namespace frc diff --git a/romiVendordep/src/main/native/include/frc/romi/RomiGyro.h b/romiVendordep/src/main/native/include/frc/romi/RomiGyro.h index 363daf3a31..5ef5045660 100644 --- a/romiVendordep/src/main/native/include/frc/romi/RomiGyro.h +++ b/romiVendordep/src/main/native/include/frc/romi/RomiGyro.h @@ -8,6 +8,11 @@ namespace frc { +/** + * @ingroup romi_api + * @{ + */ + /** * Use a rate gyro to return the robots heading relative to a starting position. * @@ -88,4 +93,6 @@ class RomiGyro { double m_angleZOffset = 0; }; +/** @} */ + } // namespace frc diff --git a/romiVendordep/src/main/native/include/frc/romi/RomiMotor.h b/romiVendordep/src/main/native/include/frc/romi/RomiMotor.h index 4bb925056b..75bbe5b162 100644 --- a/romiVendordep/src/main/native/include/frc/romi/RomiMotor.h +++ b/romiVendordep/src/main/native/include/frc/romi/RomiMotor.h @@ -8,6 +8,11 @@ namespace frc { +/** + * @defgroup romi_api Romi Hardware API + * @{ + */ + /** * RomiMotor * @@ -27,4 +32,6 @@ class RomiMotor : public PWMMotorController { RomiMotor& operator=(RomiMotor&&) = default; }; +/** @} */ + } // namespace frc diff --git a/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPGyro.java b/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPGyro.java index f815c6f837..b1b8199e62 100644 --- a/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPGyro.java +++ b/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPGyro.java @@ -27,7 +27,11 @@ public class XRPGyro { private double m_angleYOffset; private double m_angleZOffset; - /** Create a new XRPGyro. */ + /** + * Constructs an XRPGyro. + * + *

Only one instance of a XRPGyro is supported. + */ public XRPGyro() { m_simDevice = SimDevice.create("Gyro:XRPGyro"); if (m_simDevice != null) { diff --git a/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPMotor.java b/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPMotor.java index 5924cb4adb..f99173a6eb 100644 --- a/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPMotor.java +++ b/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPMotor.java @@ -44,7 +44,11 @@ public class XRPMotor implements MotorController { private final SimDouble m_simSpeed; private final SimBoolean m_simInverted; - /** XRPMotor. */ + /** + * Constructs an XRPMotor. + * + * @param deviceNum the motor channel + */ public XRPMotor(int deviceNum) { checkDeviceAllocation(deviceNum); diff --git a/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPRangefinder.java b/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPRangefinder.java index ac2d72c1f8..70dbce5924 100644 --- a/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPRangefinder.java +++ b/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPRangefinder.java @@ -11,6 +11,13 @@ import edu.wpi.first.wpilibj.AnalogInput; public class XRPRangefinder { private final AnalogInput m_rangefinder = new AnalogInput(2); + /** + * Constructs an XRPRangefinder. + * + *

Only one instance of a XRPRangefinder is supported. + */ + public XRPRangefinder() {} + /** * Get the measured distance in meters. Distance further than 4m will be reported as 4m. * diff --git a/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPReflectanceSensor.java b/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPReflectanceSensor.java index ebd5368db8..623215bf55 100644 --- a/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPReflectanceSensor.java +++ b/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPReflectanceSensor.java @@ -11,6 +11,13 @@ public class XRPReflectanceSensor { private final AnalogInput m_leftSensor = new AnalogInput(0); private final AnalogInput m_rightSensor = new AnalogInput(1); + /** + * Constructs an XRPReflectanceSensor. + * + *

Only one instance of a XRPReflectanceSensor is supported. + */ + public XRPReflectanceSensor() {} + /** * Returns the reflectance value of the left sensor. * diff --git a/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPServo.java b/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPServo.java index ac7231fd22..73901e4bfa 100644 --- a/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPServo.java +++ b/xrpVendordep/src/main/java/edu/wpi/first/wpilibj/xrp/XRPServo.java @@ -38,7 +38,11 @@ public class XRPServo { private final SimDouble m_simPosition; - /** XRPServo. */ + /** + * Constructs an XRPServo. + * + * @param deviceNum the servo channel + */ public XRPServo(int deviceNum) { checkDeviceAllocation(deviceNum); @@ -58,18 +62,18 @@ public class XRPServo { /** * Set the servo angle. * - * @param angle Desired angle in degrees + * @param angleDegrees Desired angle in degrees */ - public void setAngle(double angle) { - if (angle < 0.0) { - angle = 0.0; + public void setAngle(double angleDegrees) { + if (angleDegrees < 0.0) { + angleDegrees = 0.0; } - if (angle > 180.0) { - angle = 180.0; + if (angleDegrees > 180.0) { + angleDegrees = 180.0; } - double pos = angle / 180.0; + double pos = angleDegrees / 180.0; if (m_simPosition != null) { m_simPosition.set(pos); @@ -92,19 +96,19 @@ public class XRPServo { /** * Set the servo position. * - * @param pos Desired position (Between 0.0 and 1.0) + * @param position Desired position (Between 0.0 and 1.0) */ - public void setPosition(double pos) { - if (pos < 0.0) { - pos = 0.0; + public void setPosition(double position) { + if (position < 0.0) { + position = 0.0; } - if (pos > 1.0) { - pos = 1.0; + if (position > 1.0) { + position = 1.0; } if (m_simPosition != null) { - m_simPosition.set(pos); + m_simPosition.set(position); } } diff --git a/xrpVendordep/src/main/native/include/frc/xrp/XRPGyro.h b/xrpVendordep/src/main/native/include/frc/xrp/XRPGyro.h index 81b1610872..1cf49a7710 100644 --- a/xrpVendordep/src/main/native/include/frc/xrp/XRPGyro.h +++ b/xrpVendordep/src/main/native/include/frc/xrp/XRPGyro.h @@ -8,6 +8,11 @@ namespace frc { +/** + * @ingroup xrp_api + * @{ + */ + /** * Use a rate gyro to return the robots heading relative to a starting position. * @@ -16,6 +21,11 @@ namespace frc { */ class XRPGyro { public: + /** + * Constructs an XRPGyro. + * + *

Only one instance of a XRPGyro is supported. + */ XRPGyro(); /** @@ -88,4 +98,6 @@ class XRPGyro { double m_angleZOffset = 0; }; +/** @} */ + } // namespace frc diff --git a/xrpVendordep/src/main/native/include/frc/xrp/XRPMotor.h b/xrpVendordep/src/main/native/include/frc/xrp/XRPMotor.h index 8a220c0800..f9e96c1fe7 100644 --- a/xrpVendordep/src/main/native/include/frc/xrp/XRPMotor.h +++ b/xrpVendordep/src/main/native/include/frc/xrp/XRPMotor.h @@ -18,8 +18,18 @@ namespace frc { WPI_IGNORE_DEPRECATED +/** + * @defgroup xrp_api XRP Hardware API + * @{ + */ + class XRPMotor : public frc::MotorController, public frc::MotorSafety { public: + /** + * Constructs an XRPMotor. + * + * @param deviceNum the motor channel + */ explicit XRPMotor(int deviceNum); void Set(double value) override; @@ -46,6 +56,8 @@ class XRPMotor : public frc::MotorController, public frc::MotorSafety { static void CheckDeviceAllocation(int deviceNum); }; +/** @} */ + WPI_UNIGNORE_DEPRECATED } // namespace frc diff --git a/xrpVendordep/src/main/native/include/frc/xrp/XRPOnBoardIO.h b/xrpVendordep/src/main/native/include/frc/xrp/XRPOnBoardIO.h index 4b97870f2c..dc3e0c2114 100644 --- a/xrpVendordep/src/main/native/include/frc/xrp/XRPOnBoardIO.h +++ b/xrpVendordep/src/main/native/include/frc/xrp/XRPOnBoardIO.h @@ -13,6 +13,11 @@ namespace frc { +/** + * @ingroup xrp_api + * @{ + */ + /** * This class represents the onboard IO of the XRP * reference robot. This the USER push button and @@ -43,4 +48,6 @@ class XRPOnBoardIO { frc::DigitalOutput m_led{1}; }; +/** @} */ + } // namespace frc diff --git a/xrpVendordep/src/main/native/include/frc/xrp/XRPRangefinder.h b/xrpVendordep/src/main/native/include/frc/xrp/XRPRangefinder.h index 5be78e6784..d2b949bb86 100644 --- a/xrpVendordep/src/main/native/include/frc/xrp/XRPRangefinder.h +++ b/xrpVendordep/src/main/native/include/frc/xrp/XRPRangefinder.h @@ -10,6 +10,11 @@ namespace frc { +/** + * @ingroup xrp_api + * @{ + */ + /** * This class represents the reflectance sensor pair * on the XRP robot. @@ -26,4 +31,6 @@ class XRPRangefinder { frc::AnalogInput m_rangefinder{2}; }; +/** @} */ + } // namespace frc diff --git a/xrpVendordep/src/main/native/include/frc/xrp/XRPReflectanceSensor.h b/xrpVendordep/src/main/native/include/frc/xrp/XRPReflectanceSensor.h index 8b85cd2b64..8b1406c36f 100644 --- a/xrpVendordep/src/main/native/include/frc/xrp/XRPReflectanceSensor.h +++ b/xrpVendordep/src/main/native/include/frc/xrp/XRPReflectanceSensor.h @@ -8,6 +8,11 @@ namespace frc { +/** + * @ingroup xrp_api + * @{ + */ + /** * This class represents the reflectance sensor pair * on the XRP robot. @@ -31,4 +36,6 @@ class XRPReflectanceSensor { frc::AnalogInput m_rightSensor{1}; }; +/** @} */ + } // namespace frc diff --git a/xrpVendordep/src/main/native/include/frc/xrp/XRPServo.h b/xrpVendordep/src/main/native/include/frc/xrp/XRPServo.h index f452a5f514..4f55f30515 100644 --- a/xrpVendordep/src/main/native/include/frc/xrp/XRPServo.h +++ b/xrpVendordep/src/main/native/include/frc/xrp/XRPServo.h @@ -12,14 +12,50 @@ namespace frc { +/** + * @ingroup xrp_api + * @{ + */ + +/** + * XRPServo. + * + *

A SimDevice based servo + */ class XRPServo { public: + /** + * Constructs an XRPServo. + * @param deviceNum the servo channel + */ explicit XRPServo(int deviceNum); + /** + * Set the servo angle. + * + * @param angleDegrees Desired angle in degrees + */ void SetAngle(double angleDegrees); + + /** + * Get the servo angle. + * + * @return Current servo angle + */ double GetAngle() const; + /** + * Set the servo position. + * + * @param position Desired position (Between 0.0 and 1.0) + */ void SetPosition(double position); + + /** + * Get the servo position. + * + * @return Current servo position + */ double GetPosition() const; private: @@ -34,4 +70,6 @@ class XRPServo { static void CheckDeviceAllocation(int deviceNum); }; +/** @} */ + } // namespace frc