diff --git a/.github/workflows/lint-format.yml b/.github/workflows/lint-format.yml index a7aafe8f9c..6d806f77a0 100644 --- a/.github/workflows/lint-format.yml +++ b/.github/workflows/lint-format.yml @@ -84,3 +84,17 @@ jobs: - name: Generate diff run: git diff HEAD > javaformat-fixes.patch if: ${{ failure() }} + documentation: + name: "Documentation" + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 0 + - uses: actions/setup-java@v1 + with: + java-version: 13 + - name: Install libclang-9 + run: sudo apt update && sudo apt install -y libclang-cpp9 libclang1-9 + - name: Build with Gradle + run: ./gradlew docs:zipDocs -PbuildServer -PdocWarningsAsErrors ${{ env.EXTRA_GRADLE_ARGS }} diff --git a/cameraserver/src/main/native/include/cameraserver/CameraServer.h b/cameraserver/src/main/native/include/cameraserver/CameraServer.h index 32f96db8c0..6d087e9e27 100644 --- a/cameraserver/src/main/native/include/cameraserver/CameraServer.h +++ b/cameraserver/src/main/native/include/cameraserver/CameraServer.h @@ -229,6 +229,7 @@ class CameraServer { * Adds a MJPEG server. * * @param name Server name + * @param port Port number */ static cs::MjpegServer AddServer(std::string_view name, int port); diff --git a/cameraserver/src/main/native/include/vision/VisionRunner.h b/cameraserver/src/main/native/include/vision/VisionRunner.h index bda338e856..6e6e93adfa 100644 --- a/cameraserver/src/main/native/include/vision/VisionRunner.h +++ b/cameraserver/src/main/native/include/vision/VisionRunner.h @@ -44,7 +44,7 @@ class VisionRunnerBase { * *

This method is exposed to allow teams to add additional functionality or * have their own ways to run the pipeline. Most teams, however, should just - * use {@link #runForever} in its own thread using a std::thread.

+ * use RunForever() in its own thread using a std::thread.

*/ void RunOnce(); diff --git a/cscore/src/main/native/include/cscore_oo.h b/cscore/src/main/native/include/cscore_oo.h index f780fcd003..4fd1bff176 100644 --- a/cscore/src/main/native/include/cscore_oo.h +++ b/cscore/src/main/native/include/cscore_oo.h @@ -570,7 +570,6 @@ class AxisCamera : public HttpCamera { * * @param name Source name (arbitrary unique identifier) * @param host Camera host IP or DNS name (e.g. "10.x.y.11") - * @param kind Camera kind (e.g. kAxis) */ AxisCamera(std::string_view name, std::string_view host); @@ -579,7 +578,6 @@ class AxisCamera : public HttpCamera { * * @param name Source name (arbitrary unique identifier) * @param host Camera host IP or DNS name (e.g. "10.x.y.11") - * @param kind Camera kind (e.g. kAxis) */ AxisCamera(std::string_view name, const char* host); @@ -588,7 +586,6 @@ class AxisCamera : public HttpCamera { * * @param name Source name (arbitrary unique identifier) * @param host Camera host IP or DNS name (e.g. "10.x.y.11") - * @param kind Camera kind (e.g. kAxis) */ AxisCamera(std::string_view name, const std::string& host); @@ -597,7 +594,6 @@ class AxisCamera : public HttpCamera { * * @param name Source name (arbitrary unique identifier) * @param hosts Array of Camera host IPs/DNS names - * @param kind Camera kind (e.g. kAxis) */ AxisCamera(std::string_view name, wpi::span hosts); @@ -606,7 +602,6 @@ class AxisCamera : public HttpCamera { * * @param name Source name (arbitrary unique identifier) * @param hosts Array of Camera host IPs/DNS names - * @param kind Camera kind (e.g. kAxis) */ template AxisCamera(std::string_view name, std::initializer_list hosts); @@ -623,6 +618,8 @@ class ImageSource : public VideoSource { /** * Signal sinks that an error has occurred. This should be called instead * of NotifyFrame when an error occurs. + * + * @param msg Notification message. */ void NotifyError(std::string_view msg); @@ -686,7 +683,6 @@ class ImageSource : public VideoSource { * Create a string property. * * @param name Property name - * @param defaultValue Default value * @param value Current value * @return Property */ diff --git a/docs/build.gradle b/docs/build.gradle index 73808d16e4..e60ffdb9cc 100644 --- a/docs/build.gradle +++ b/docs/build.gradle @@ -56,29 +56,97 @@ doxygen { } } - exclude 'Eigen/**' - exclude 'unsupported/**' - exclude 'units/**' - exclude 'uv.h' - exclude 'uv/**' + if (project.hasProperty('docWarningsAsErrors')) { + // C++20 shims + exclude 'wpi/ghc/filesystem.hpp' + exclude 'wpi/span.h' + + // Drake + exclude 'drake/common/**' + + // Eigen + exclude 'Eigen/**' + exclude 'unsupported/**' + + // LLVM + exclude 'wpi/AlignOf.h' + exclude 'wpi/Chrono.h' + exclude 'wpi/Compiler.h' + exclude 'wpi/ConvertUTF.h' + exclude 'wpi/DenseMap.h' + exclude 'wpi/DenseMapInfo.h' + exclude 'wpi/Endian.h' + exclude 'wpi/EpochTracker.h' + exclude 'wpi/Errc.h' + exclude 'wpi/Errno.h' + exclude 'wpi/ErrorHandling.h' + exclude 'wpi/fs.h' + exclude 'wpi/FunctionExtras.h' + exclude 'wpi/function_ref.h' + exclude 'wpi/Hashing.h' + exclude 'wpi/IntrusiveRefCntPtr.h' + exclude 'wpi/iterator.h' + exclude 'wpi/iterator_range.h' + exclude 'wpi/ManagedStatic.h' + exclude 'wpi/MapVector.h' + exclude 'wpi/MathExtras.h' + exclude 'wpi/MemAlloc.h' + exclude 'wpi/PointerIntPair.h' + exclude 'wpi/PointerLikeTypeTraits.h' + exclude 'wpi/PointerUnion.h' + exclude 'wpi/raw_os_ostream.h' + exclude 'wpi/raw_ostream.h' + exclude 'wpi/SmallPtrSet.h' + exclude 'wpi/SmallSet.h' + exclude 'wpi/SmallString.h' + exclude 'wpi/SmallVector.h' + exclude 'wpi/StringExtras.h' + exclude 'wpi/StringMap.h' + exclude 'wpi/SwapByteOrder.h' + exclude 'wpi/type_traits.h' + exclude 'wpi/VersionTuple.h' + exclude 'wpi/WindowsError.h' + + // fmtlib + exclude 'fmt/**' + + // libuv + exclude 'uv.h' + exclude 'uv/**' + exclude 'wpi/uv/**' + + // json + exclude 'wpi/json.h' + + // units + exclude 'units/**' + } extension_mapping 'inc=C++' + extract_static true + full_path_names true + generate_html true + generate_latex false + generate_treeview true + html_extra_stylesheet 'theme.css' + html_timestamp true + javadoc_autobrief true project_name 'WPILibC++' project_logo '../wpiutil/src/main/native/resources/wpilib-128.png' project_number wpilibVersioning.version.get() - javadoc_autobrief true - recursive true quiet true - warnings false - warn_if_undocumented false - generate_latex false - use_mathjax true - html_timestamp true - generate_treeview true - extract_static true - full_path_names true + recursive true strip_from_inc_path cppIncludeRoots as String[] strip_from_path cppIncludeRoots as String[] + use_mathjax true + warnings false + warn_if_incomplete_doc true + warn_if_undocumented false + warn_no_paramdoc true + + if (project.hasProperty('docWarningsAsErrors')) { + warn_as_error 'FAIL_ON_WARNINGS' + } } tasks.register("zipCppDocs", Zip) { @@ -133,7 +201,7 @@ task generateJavaDocs(type: Javadoc) { title = "WPILib API ${wpilibVersioning.version.get()}" ext.entryPoint = "$destinationDir/index.html" - if (JavaVersion.current().isJava8Compatible() && project.hasProperty('buildServer')) { + if (JavaVersion.current().isJava8Compatible() && project.hasProperty('docWarningsAsErrors')) { // Treat javadoc warnings as errors. // // The second argument '-quiet' is a hack. The one paramater diff --git a/hal/src/main/native/athena/CTREPDP.h b/hal/src/main/native/athena/CTREPDP.h index 43ec031d35..dd4b298d5c 100644 --- a/hal/src/main/native/athena/CTREPDP.h +++ b/hal/src/main/native/athena/CTREPDP.h @@ -44,7 +44,7 @@ int32_t HAL_GetPDPModuleNumber(HAL_PDPHandle handle, int32_t* status); * Checks if a PDP channel is valid. * * @param channel the channel to check - * @return true if the channel is valid, otherwise false + * @return true if the channel is valid, otherwise false */ HAL_Bool HAL_CheckPDPChannel(int32_t channel); @@ -52,7 +52,7 @@ HAL_Bool HAL_CheckPDPChannel(int32_t channel); * Checks if a PDP module is valid. * * @param channel the module to check - * @return true if the module is valid, otherwise false + * @return true if the module is valid, otherwise false */ HAL_Bool HAL_CheckPDPModule(int32_t module); @@ -60,7 +60,7 @@ HAL_Bool HAL_CheckPDPModule(int32_t module); * Gets the temperature of the PDP. * * @param handle the module handle - * @return the module temperature (celsius) + * @return the module temperature (celsius) */ double HAL_GetPDPTemperature(HAL_PDPHandle handle, int32_t* status); @@ -68,7 +68,7 @@ double HAL_GetPDPTemperature(HAL_PDPHandle handle, int32_t* status); * Gets the PDP input voltage. * * @param handle the module handle - * @return the input voltage (volts) + * @return the input voltage (volts) */ double HAL_GetPDPVoltage(HAL_PDPHandle handle, int32_t* status); @@ -77,7 +77,7 @@ double HAL_GetPDPVoltage(HAL_PDPHandle handle, int32_t* status); * * @param module the module * @param channel the channel - * @return the channel current (amps) + * @return the channel current (amps) */ double HAL_GetPDPChannelCurrent(HAL_PDPHandle handle, int32_t channel, int32_t* status); @@ -97,7 +97,7 @@ void HAL_GetPDPAllChannelCurrents(HAL_PDPHandle handle, double* currents, * Gets the total current of the PDP. * * @param handle the module handle - * @return the total current (amps) + * @return the total current (amps) */ double HAL_GetPDPTotalCurrent(HAL_PDPHandle handle, int32_t* status); @@ -105,7 +105,7 @@ double HAL_GetPDPTotalCurrent(HAL_PDPHandle handle, int32_t* status); * Gets the total power of the PDP. * * @param handle the module handle - * @return the total power (watts) + * @return the total power (watts) */ double HAL_GetPDPTotalPower(HAL_PDPHandle handle, int32_t* status); @@ -113,7 +113,7 @@ double HAL_GetPDPTotalPower(HAL_PDPHandle handle, int32_t* status); * Gets the total energy of the PDP. * * @param handle the module handle - * @return the total energy (joules) + * @return the total energy (joules) */ double HAL_GetPDPTotalEnergy(HAL_PDPHandle handle, int32_t* status); diff --git a/hal/src/main/native/athena/FRCDriverStation.cpp b/hal/src/main/native/athena/FRCDriverStation.cpp index 87abf439d4..0f4b69b46c 100644 --- a/hal/src/main/native/athena/FRCDriverStation.cpp +++ b/hal/src/main/native/athena/FRCDriverStation.cpp @@ -69,15 +69,15 @@ static int32_t HAL_GetJoystickButtonsInternal(int32_t joystickNum, joystickNum, &buttons->buttons, &buttons->count); } /** - * Retrieve the Joystick Descriptor for particular slot - * @param desc [out] descriptor (data transfer object) to fill in. desc is - * filled in regardless of success. In other words, if descriptor is not - * available, desc is filled in with default values matching the init-values in - * Java and C++ Driverstation for when caller requests a too-large joystick - * index. + * Retrieve the Joystick Descriptor for particular slot. * + * @param[out] desc descriptor (data transfer object) to fill in. desc is filled + * in regardless of success. In other words, if descriptor is + * not available, desc is filled in with default values + * matching the init-values in Java and C++ Driverstation for + * when caller requests a too-large joystick index. * @return error code reported from Network Comm back-end. Zero is good, - * nonzero is bad. + * nonzero is bad. */ static int32_t HAL_GetJoystickDescriptorInternal(int32_t joystickNum, HAL_JoystickDescriptor* desc) { diff --git a/hal/src/main/native/athena/HAL.cpp b/hal/src/main/native/athena/HAL.cpp index f344b005f5..0b6d05efae 100644 --- a/hal/src/main/native/athena/HAL.cpp +++ b/hal/src/main/native/athena/HAL.cpp @@ -280,10 +280,10 @@ uint64_t HAL_GetFPGATime(int32_t* status) { return (upper2 << 32) + lower; } -uint64_t HAL_ExpandFPGATime(uint32_t unexpanded_lower, int32_t* status) { +uint64_t HAL_ExpandFPGATime(uint32_t unexpandedLower, int32_t* status) { // Capture the current FPGA time. This will give us the upper half of the // clock. - uint64_t fpga_time = HAL_GetFPGATime(status); + uint64_t fpgaTime = HAL_GetFPGATime(status); if (*status != 0) { return 0; } @@ -293,15 +293,15 @@ uint64_t HAL_ExpandFPGATime(uint32_t unexpanded_lower, int32_t* status) { // be. // Break it into lower and upper portions. - uint32_t lower = fpga_time & 0xffffffffull; - uint64_t upper = (fpga_time >> 32) & 0xffffffff; + uint32_t lower = fpgaTime & 0xffffffffull; + uint64_t upper = (fpgaTime >> 32) & 0xffffffff; // The time was sampled *before* the current time, so roll it back. - if (lower < unexpanded_lower) { + if (lower < unexpandedLower) { --upper; } - return (upper << 32) + static_cast(unexpanded_lower); + return (upper << 32) + static_cast(unexpandedLower); } HAL_Bool HAL_GetFPGAButton(int32_t* status) { diff --git a/hal/src/main/native/athena/REVPDH.h b/hal/src/main/native/athena/REVPDH.h index ed96af7f0c..228d05cec9 100644 --- a/hal/src/main/native/athena/REVPDH.h +++ b/hal/src/main/native/athena/REVPDH.h @@ -30,7 +30,7 @@ extern "C" { * Initializes a REV Power Distribution Hub (PDH) device. * * @param module the device CAN ID (1 .. 63) - * @return the created PDH handle + * @return the created PDH handle */ HAL_REVPDHHandle HAL_REV_InitializePDH(int32_t module, const char* allocationLocation, @@ -54,7 +54,7 @@ int32_t HAL_REV_GetPDHModuleNumber(HAL_REVPDHHandle handle, int32_t* status); * Does not check if a PDH device with this module has been initialized. * * @param module module number (1 .. 63) - * @return 1 if the module number is valid; 0 otherwise + * @return 1 if the module number is valid; 0 otherwise */ HAL_Bool HAL_REV_CheckPDHModuleNumber(int32_t module); @@ -62,7 +62,7 @@ HAL_Bool HAL_REV_CheckPDHModuleNumber(int32_t module); * Checks if a PDH channel number is valid. * * @param module channel number (0 .. HAL_REV_PDH_NUM_CHANNELS) - * @return 1 if the channel number is valid; 0 otherwise + * @return 1 if the channel number is valid; 0 otherwise */ HAL_Bool HAL_REV_CheckPDHChannelNumber(int32_t channel); @@ -73,7 +73,7 @@ HAL_Bool HAL_REV_CheckPDHChannelNumber(int32_t channel); * @param channel the channel to retrieve the current of (0 .. * HAL_REV_PDH_NUM_CHANNELS) * - * @return the current of the PDH channel in Amps + * @return the current of the PDH channel in Amps */ double HAL_REV_GetPDHChannelCurrent(HAL_REVPDHHandle handle, int32_t channel, int32_t* status); @@ -91,7 +91,7 @@ void HAL_REV_GetPDHAllChannelCurrents(HAL_REVPDHHandle handle, double* currents, * * @param handle PDH handle * - * @return the total current of the PDH in Amps + * @return the total current of the PDH in Amps */ uint16_t HAL_REV_GetPDHTotalCurrent(HAL_REVPDHHandle handle, int32_t* status); @@ -112,7 +112,7 @@ void HAL_REV_SetPDHSwitchableChannel(HAL_REVPDHHandle handle, HAL_Bool enabled, * fresh as the last packet received. * * @param handle PDH handle - * @return 1 if the switchable channel is enabled; 0 otherwise + * @return 1 if the switchable channel is enabled; 0 otherwise */ HAL_Bool HAL_REV_GetPDHSwitchableChannelState(HAL_REVPDHHandle handle, int32_t* status); @@ -125,7 +125,7 @@ HAL_Bool HAL_REV_GetPDHSwitchableChannelState(HAL_REVPDHHandle handle, * @param handle PDH handle * @param channel the channel to retrieve the brownout status of * - * @return 1 if the channel is experiencing a brownout; 0 otherwise + * @return 1 if the channel is experiencing a brownout; 0 otherwise */ HAL_Bool HAL_REV_CheckPDHChannelBrownout(HAL_REVPDHHandle handle, int32_t channel, int32_t* status); @@ -135,7 +135,7 @@ HAL_Bool HAL_REV_CheckPDHChannelBrownout(HAL_REVPDHHandle handle, * * @param handle PDH handle * - * @return the voltage at the input of the PDH in Volts + * @return the voltage at the input of the PDH in Volts */ double HAL_REV_GetPDHSupplyVoltage(HAL_REVPDHHandle handle, int32_t* status); @@ -144,7 +144,7 @@ double HAL_REV_GetPDHSupplyVoltage(HAL_REVPDHHandle handle, int32_t* status); * * @param handle PDH handle * - * @return 1 if the PDH is enabled; 0 otherwise + * @return 1 if the PDH is enabled; 0 otherwise */ HAL_Bool HAL_REV_IsPDHEnabled(HAL_REVPDHHandle handle, int32_t* status); @@ -156,7 +156,7 @@ HAL_Bool HAL_REV_IsPDHEnabled(HAL_REVPDHHandle handle, int32_t* status); * * @param handle PDH handle * - * @return 1 if the PDH is experiencing a brownout; 0 otherwise + * @return 1 if the PDH is experiencing a brownout; 0 otherwise */ HAL_Bool HAL_REV_CheckPDHBrownout(HAL_REVPDHHandle handle, int32_t* status); @@ -168,7 +168,7 @@ HAL_Bool HAL_REV_CheckPDHBrownout(HAL_REVPDHHandle handle, int32_t* status); * * @param handle PDH handle * - * @return 1 if the device has exceeded the warning threshold; 0 + * @return 1 if the device has exceeded the warning threshold; 0 * otherwise */ HAL_Bool HAL_REV_CheckPDHCANWarning(HAL_REVPDHHandle handle, int32_t* status); @@ -180,7 +180,7 @@ HAL_Bool HAL_REV_CheckPDHCANWarning(HAL_REVPDHHandle handle, int32_t* status); * * @param handle PDH handle * - * @return 1 if the device is in a hardware fault state; 0 + * @return 1 if the device is in a hardware fault state; 0 * otherwise */ HAL_Bool HAL_REV_CheckPDHHardwareFault(HAL_REVPDHHandle handle, @@ -194,7 +194,7 @@ HAL_Bool HAL_REV_CheckPDHHardwareFault(HAL_REVPDHHandle handle, * * @param handle PDH handle * - * @return 1 if the device has had a brownout; 0 otherwise + * @return 1 if the device has had a brownout; 0 otherwise */ HAL_Bool HAL_REV_CheckPDHStickyBrownout(HAL_REVPDHHandle handle, int32_t* status); @@ -207,7 +207,7 @@ HAL_Bool HAL_REV_CheckPDHStickyBrownout(HAL_REVPDHHandle handle, * * @param handle PDH handle * - * @return 1 if the device has exceeded the CAN warning threshold; + * @return 1 if the device has exceeded the CAN warning threshold; * 0 otherwise */ HAL_Bool HAL_REV_CheckPDHStickyCANWarning(HAL_REVPDHHandle handle, @@ -221,7 +221,7 @@ HAL_Bool HAL_REV_CheckPDHStickyCANWarning(HAL_REVPDHHandle handle, * * @param handle PDH handle * - * @return 1 if the device has experienced a 'Bus Off' event; 0 + * @return 1 if the device has experienced a 'Bus Off' event; 0 * otherwise */ HAL_Bool HAL_REV_CheckPDHStickyCANBusOff(HAL_REVPDHHandle handle, @@ -234,7 +234,7 @@ HAL_Bool HAL_REV_CheckPDHStickyCANBusOff(HAL_REVPDHHandle handle, * * @param handle PDH handle * - * @return 1 if the device has had a malfunction; 0 otherwise + * @return 1 if the device has had a malfunction; 0 otherwise */ HAL_Bool HAL_REV_CheckPDHStickyHardwareFault(HAL_REVPDHHandle handle, int32_t* status); @@ -247,7 +247,7 @@ HAL_Bool HAL_REV_CheckPDHStickyHardwareFault(HAL_REVPDHHandle handle, * * @param handle PDH handle * - * @return 1 if the device has had a malfunction and reset; 0 + * @return 1 if the device has had a malfunction and reset; 0 * otherwise */ HAL_Bool HAL_REV_CheckPDHStickyFirmwareFault(HAL_REVPDHHandle handle, @@ -264,7 +264,7 @@ HAL_Bool HAL_REV_CheckPDHStickyFirmwareFault(HAL_REVPDHHandle handle, * 23) * * - * @return 1 if the channel has had a brownout; 0 otherwise + * @return 1 if the channel has had a brownout; 0 otherwise */ HAL_Bool HAL_REV_CheckPDHStickyChannelBrownout(HAL_REVPDHHandle handle, int32_t channel, @@ -277,7 +277,7 @@ HAL_Bool HAL_REV_CheckPDHStickyChannelBrownout(HAL_REVPDHHandle handle, * * @param handle PDH handle * - * @return 1 if the device has reset; 0 otherwise + * @return 1 if the device has reset; 0 otherwise */ HAL_Bool HAL_REV_CheckPDHStickyHasReset(HAL_REVPDHHandle handle, int32_t* status); @@ -287,7 +287,7 @@ HAL_Bool HAL_REV_CheckPDHStickyHasReset(HAL_REVPDHHandle handle, * * @param handle PDH handle * - * @return version information + * @return version information */ REV_PDH_Version HAL_REV_GetPDHVersion(HAL_REVPDHHandle handle, int32_t* status); diff --git a/hal/src/main/native/include/hal/AnalogAccumulator.h b/hal/src/main/native/include/hal/AnalogAccumulator.h index 3c6dfab9b3..c0c928df81 100644 --- a/hal/src/main/native/include/hal/AnalogAccumulator.h +++ b/hal/src/main/native/include/hal/AnalogAccumulator.h @@ -21,7 +21,8 @@ extern "C" { /** * Is the channel attached to an accumulator. * - * @param analogPortHandle Handle to the analog port. + * @param[in] analogPortHandle Handle to the analog port. + * @param[out] status Error status variable. 0 on success. * @return The analog channel is attached to an accumulator. */ HAL_Bool HAL_IsAccumulatorChannel(HAL_AnalogInputHandle analogPortHandle, @@ -30,7 +31,8 @@ HAL_Bool HAL_IsAccumulatorChannel(HAL_AnalogInputHandle analogPortHandle, /** * Initialize the accumulator. * - * @param analogPortHandle Handle to the analog port. + * @param[in] analogPortHandle Handle to the analog port. + * @param[out] status Error status variable. 0 on success. */ void HAL_InitAccumulator(HAL_AnalogInputHandle analogPortHandle, int32_t* status); @@ -38,7 +40,8 @@ void HAL_InitAccumulator(HAL_AnalogInputHandle analogPortHandle, /** * Resets the accumulator to the initial value. * - * @param analogPortHandle Handle to the analog port. + * @param[in] analogPortHandle Handle to the analog port. + * @param[out] status Error status variable. 0 on success. */ void HAL_ResetAccumulator(HAL_AnalogInputHandle analogPortHandle, int32_t* status); @@ -55,8 +58,9 @@ void HAL_ResetAccumulator(HAL_AnalogInputHandle analogPortHandle, * source from channel 1. Because of this, any non-zero oversample bits will * affect the size of the value for this field. * - * @param analogPortHandle Handle to the analog port. - * @param center The center value of the accumulator. + * @param[in] analogPortHandle Handle to the analog port. + * @param[in] center The center value of the accumulator. + * @param[out] status Error status variable. 0 on success. */ void HAL_SetAccumulatorCenter(HAL_AnalogInputHandle analogPortHandle, int32_t center, int32_t* status); @@ -64,8 +68,9 @@ void HAL_SetAccumulatorCenter(HAL_AnalogInputHandle analogPortHandle, /** * Set the accumulator's deadband. * - * @param analogPortHandle Handle to the analog port. - * @param deadband The deadband of the accumulator. + * @param[in] analogPortHandle Handle to the analog port. + * @param[in] deadband The deadband of the accumulator. + * @param[out] status Error status variable. 0 on success. */ void HAL_SetAccumulatorDeadband(HAL_AnalogInputHandle analogPortHandle, int32_t deadband, int32_t* status); @@ -76,7 +81,8 @@ void HAL_SetAccumulatorDeadband(HAL_AnalogInputHandle analogPortHandle, * Read the value that has been accumulating on channel 1. * The accumulator is attached after the oversample and average engine. * - * @param analogPortHandle Handle to the analog port. + * @param[in] analogPortHandle Handle to the analog port. + * @param[out] status Error status variable. 0 on success. * @return The 64-bit value accumulated since the last Reset(). */ int64_t HAL_GetAccumulatorValue(HAL_AnalogInputHandle analogPortHandle, @@ -88,7 +94,8 @@ int64_t HAL_GetAccumulatorValue(HAL_AnalogInputHandle analogPortHandle, * Read the count of the accumulated values since the accumulator was last * Reset(). * - * @param analogPortHandle Handle to the analog port. + * @param[in] analogPortHandle Handle to the analog port. + * @param[out] status Error status variable. 0 on success. * @return The number of times samples from the channel were accumulated. */ int64_t HAL_GetAccumulatorCount(HAL_AnalogInputHandle analogPortHandle, @@ -100,9 +107,10 @@ int64_t HAL_GetAccumulatorCount(HAL_AnalogInputHandle analogPortHandle, * This function reads the value and count from the FPGA atomically. * This can be used for averaging. * - * @param analogPortHandle Handle to the analog port. - * @param value Pointer to the 64-bit accumulated output. - * @param count Pointer to the number of accumulation cycles. + * @param[in] analogPortHandle Handle to the analog port. + * @param[in] value Pointer to the 64-bit accumulated output. + * @param[in] count Pointer to the number of accumulation cycles. + * @param[out] status Error status variable. 0 on success. */ void HAL_GetAccumulatorOutput(HAL_AnalogInputHandle analogPortHandle, int64_t* value, int64_t* count, int32_t* status); diff --git a/hal/src/main/native/include/hal/AnalogGyro.h b/hal/src/main/native/include/hal/AnalogGyro.h index 16171b1384..6e5a9c24d6 100644 --- a/hal/src/main/native/include/hal/AnalogGyro.h +++ b/hal/src/main/native/include/hal/AnalogGyro.h @@ -21,10 +21,11 @@ extern "C" { /** * Initializes an analog gyro. * - * @param handle handle to the analog port - * @param allocationLocation the location where the allocation is occuring - * (can be null) - * @return the initialized gyro handle + * @param[in] handle handle to the analog port + * @param[in] allocationLocation the location where the allocation is occuring + * (can be null) + * @param[out] status the error code, or 0 for success + * @return the initialized gyro handle */ HAL_GyroHandle HAL_InitializeAnalogGyro(HAL_AnalogInputHandle handle, const char* allocationLocation, @@ -34,7 +35,8 @@ HAL_GyroHandle HAL_InitializeAnalogGyro(HAL_AnalogInputHandle handle, * Sets up an analog gyro with the proper offsets and settings for the KOP * analog gyro. * - * @param handle the gyro handle + * @param[in] handle the gyro handle + * @param[out] status the error code, or 0 for success */ void HAL_SetupAnalogGyro(HAL_GyroHandle handle, int32_t* status); @@ -51,10 +53,11 @@ void HAL_FreeAnalogGyro(HAL_GyroHandle handle); * This is meant to be used if you want to reuse the values from a previous * calibration. * - * @param handle the gyro handle - * @param voltsPerDegreePerSecond the gyro volts scaling - * @param offset the gyro offset - * @param center the gyro center + * @param[in] handle the gyro handle + * @param[in] voltsPerDegreePerSecond the gyro volts scaling + * @param[in] offset the gyro offset + * @param[in] center the gyro center + * @param[out] status the error code, or 0 for success */ void HAL_SetAnalogGyroParameters(HAL_GyroHandle handle, double voltsPerDegreePerSecond, double offset, @@ -63,8 +66,9 @@ void HAL_SetAnalogGyroParameters(HAL_GyroHandle handle, /** * Sets the analog gyro volts per degrees per second scaling. * - * @param handle the gyro handle - * @param voltsPerDegreePerSecond the gyro volts scaling + * @param[in] handle the gyro handle + * @param[in] voltsPerDegreePerSecond the gyro volts scaling + * @param[out] status the error code, or 0 for success */ void HAL_SetAnalogGyroVoltsPerDegreePerSecond(HAL_GyroHandle handle, double voltsPerDegreePerSecond, @@ -73,7 +77,8 @@ void HAL_SetAnalogGyroVoltsPerDegreePerSecond(HAL_GyroHandle handle, /** * Resets the analog gyro value to 0. * - * @param handle the gyro handle + * @param[in] handle the gyro handle + * @param[out] status the error code, or 0 for success */ void HAL_ResetAnalogGyro(HAL_GyroHandle handle, int32_t* status); @@ -84,15 +89,17 @@ void HAL_ResetAnalogGyro(HAL_GyroHandle handle, int32_t* status); * setting that as the center. Note that this call blocks for 5 seconds to * perform this. * - * @param handle the gyro handle + * @param[in] handle the gyro handle + * @param[out] status Error status variable. 0 on success. */ void HAL_CalibrateAnalogGyro(HAL_GyroHandle handle, int32_t* status); /** * Sets the deadband of the analog gyro. * - * @param handle the gyro handle - * @param volts the voltage deadband + * @param[in] handle the gyro handle + * @param[in] volts the voltage deadband + * @param[out] status Error status variable. 0 on success. */ void HAL_SetAnalogGyroDeadband(HAL_GyroHandle handle, double volts, int32_t* status); @@ -100,7 +107,8 @@ void HAL_SetAnalogGyroDeadband(HAL_GyroHandle handle, double volts, /** * Gets the gyro angle in degrees. * - * @param handle the gyro handle + * @param[in] handle the gyro handle + * @param[out] status Error status variable. 0 on success. * @return the gyro angle in degrees */ double HAL_GetAnalogGyroAngle(HAL_GyroHandle handle, int32_t* status); @@ -108,7 +116,8 @@ double HAL_GetAnalogGyroAngle(HAL_GyroHandle handle, int32_t* status); /** * Gets the gyro rate in degrees/second. * - * @param handle the gyro handle + * @param[in] handle the gyro handle + * @param[out] status Error status variable. 0 on success. * @return the gyro rate in degrees/second */ double HAL_GetAnalogGyroRate(HAL_GyroHandle handle, int32_t* status); @@ -118,7 +127,8 @@ double HAL_GetAnalogGyroRate(HAL_GyroHandle handle, int32_t* status); * * Can be used to not repeat a calibration but reconstruct the gyro object. * - * @param handle the gyro handle + * @param[in] handle the gyro handle + * @param[out] status Error status variable. 0 on success. * @return the gryo offset */ double HAL_GetAnalogGyroOffset(HAL_GyroHandle handle, int32_t* status); @@ -128,7 +138,8 @@ double HAL_GetAnalogGyroOffset(HAL_GyroHandle handle, int32_t* status); * * Can be used to not repeat a calibration but reconstruct the gyro object. * - * @param handle the gyro handle + * @param[in] handle the gyro handle + * @param[out] status Error status variable. 0 on success. * @return the gyro center */ int32_t HAL_GetAnalogGyroCenter(HAL_GyroHandle handle, int32_t* status); diff --git a/hal/src/main/native/include/hal/AnalogInput.h b/hal/src/main/native/include/hal/AnalogInput.h index 8275ea26d1..956cd217b8 100644 --- a/hal/src/main/native/include/hal/AnalogInput.h +++ b/hal/src/main/native/include/hal/AnalogInput.h @@ -21,10 +21,11 @@ extern "C" { /** * Initializes the analog input port using the given port object. * - * @param portHandle Handle to the port to initialize. - * @param allocationLocation the location where the allocation is occuring - * (can be null) - * @return the created analog input handle + * @param[in] portHandle Handle to the port to initialize. + * @param[in] allocationLocation the location where the allocation is occuring + * (can be null) + * @param[out] status the error code, or 0 for success + * @return the created analog input handle */ HAL_AnalogInputHandle HAL_InitializeAnalogInputPort( HAL_PortHandle portHandle, const char* allocationLocation, int32_t* status); @@ -68,7 +69,8 @@ void HAL_SetAnalogInputSimDevice(HAL_AnalogInputHandle handle, * * This is a global setting for the Athena and effects all channels. * - * @param samplesPerSecond The number of samples per channel per second. + * @param[in] samplesPerSecond The number of samples per channel per second. + * @param[out] status the error code, or 0 for success */ void HAL_SetAnalogSampleRate(double samplesPerSecond, int32_t* status); @@ -78,6 +80,7 @@ void HAL_SetAnalogSampleRate(double samplesPerSecond, int32_t* status); * This assumes one entry in the scan list. * This is a global setting for the Athena and effects all channels. * + * @param[out] status the error code, or 0 for success * @return Sample rate. */ double HAL_GetAnalogSampleRate(int32_t* status); @@ -89,8 +92,9 @@ double HAL_GetAnalogSampleRate(int32_t* status); * is 2**bits. Use averaging to improve the stability of your measurement at the * expense of sampling rate. The averaging is done automatically in the FPGA. * - * @param analogPortHandle Handle to the analog port to configure. - * @param bits Number of bits to average. + * @param[in] analogPortHandle Handle to the analog port to configure. + * @param[in] bits Number of bits to average. + * @param[out] status the error code, or 0 for success */ void HAL_SetAnalogAverageBits(HAL_AnalogInputHandle analogPortHandle, int32_t bits, int32_t* status); @@ -101,7 +105,8 @@ void HAL_SetAnalogAverageBits(HAL_AnalogInputHandle analogPortHandle, * This gets the number of averaging bits from the FPGA. The actual number of * averaged samples is 2**bits. The averaging is done automatically in the FPGA. * - * @param analogPortHandle Handle to the analog port to use. + * @param[in] analogPortHandle Handle to the analog port to use. + * @param[out] status the error code, or 0 for success * @return Bits to average. */ int32_t HAL_GetAnalogAverageBits(HAL_AnalogInputHandle analogPortHandle, @@ -115,8 +120,9 @@ int32_t HAL_GetAnalogAverageBits(HAL_AnalogInputHandle analogPortHandle, * measurements at the expense of sampling rate. The oversampling is done * automatically in the FPGA. * - * @param analogPortHandle Handle to the analog port to use. - * @param bits Number of bits to oversample. + * @param[in] analogPortHandle Handle to the analog port to use. + * @param[in] bits Number of bits to oversample. + * @param[out] status the error code, or 0 for success */ void HAL_SetAnalogOversampleBits(HAL_AnalogInputHandle analogPortHandle, int32_t bits, int32_t* status); @@ -128,7 +134,8 @@ void HAL_SetAnalogOversampleBits(HAL_AnalogInputHandle analogPortHandle, * oversampled values is 2**bits. The oversampling is done automatically in the * FPGA. * - * @param analogPortHandle Handle to the analog port to use. + * @param[in] analogPortHandle Handle to the analog port to use. + * @param[out] status the error code, or 0 for success * @return Bits to oversample. */ int32_t HAL_GetAnalogOversampleBits(HAL_AnalogInputHandle analogPortHandle, @@ -141,7 +148,8 @@ int32_t HAL_GetAnalogOversampleBits(HAL_AnalogInputHandle analogPortHandle, * converter in the module. The units are in A/D converter codes. Use * GetVoltage() to get the analog value in calibrated units. * - * @param analogPortHandle Handle to the analog port to use. + * @param[in] analogPortHandle Handle to the analog port to use. + * @param[out] status the error code, or 0 for success * @return A sample straight from the channel on this module. */ int32_t HAL_GetAnalogValue(HAL_AnalogInputHandle analogPortHandle, @@ -158,7 +166,8 @@ int32_t HAL_GetAnalogValue(HAL_AnalogInputHandle analogPortHandle, * the module on this channel. Use GetAverageVoltage() to get the analog value * in calibrated units. * - * @param analogPortHandle Handle to the analog port to use. + * @param[in] analogPortHandle Handle to the analog port to use. + * @param[out] status the error code, or 0 for success * @return A sample from the oversample and average engine for the channel. */ int32_t HAL_GetAnalogAverageValue(HAL_AnalogInputHandle analogPortHandle, @@ -172,8 +181,9 @@ int32_t HAL_GetAnalogAverageValue(HAL_AnalogInputHandle analogPortHandle, * * @todo This assumes raw values. Oversampling not supported as is. * - * @param analogPortHandle Handle to the analog port to use. - * @param voltage The voltage to convert. + * @param[in] analogPortHandle Handle to the analog port to use. + * @param[in] voltage The voltage to convert. + * @param[out] status the error code, or 0 for success * @return The raw value for the channel. */ int32_t HAL_GetAnalogVoltsToValue(HAL_AnalogInputHandle analogPortHandle, @@ -185,7 +195,8 @@ int32_t HAL_GetAnalogVoltsToValue(HAL_AnalogInputHandle analogPortHandle, * The value is scaled to units of Volts using the calibrated scaling data from * GetLSBWeight() and GetOffset(). * - * @param analogPortHandle Handle to the analog port to use. + * @param[in] analogPortHandle Handle to the analog port to use. + * @param[out] status the error code, or 0 for success * @return A scaled sample straight from the channel on this module. */ double HAL_GetAnalogVoltage(HAL_AnalogInputHandle analogPortHandle, @@ -200,7 +211,8 @@ double HAL_GetAnalogVoltage(HAL_AnalogInputHandle analogPortHandle, * be higher resolution, but it will update more slowly. Using averaging will * cause this value to be more stable, but it will update more slowly. * - * @param analogPortHandle Handle to the analog port to use. + * @param[in] analogPortHandle Handle to the analog port to use. + * @param[out] status the error code, or 0 for success * @return A scaled sample from the output of the oversample and average engine * for the channel. */ @@ -214,7 +226,8 @@ double HAL_GetAnalogAverageVoltage(HAL_AnalogInputHandle analogPortHandle, * * Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9) * - * @param analogPortHandle Handle to the analog port to use. + * @param[in] analogPortHandle Handle to the analog port to use. + * @param[out] status the error code, or 0 for success * @return Least significant bit weight. */ int32_t HAL_GetAnalogLSBWeight(HAL_AnalogInputHandle analogPortHandle, @@ -227,7 +240,8 @@ int32_t HAL_GetAnalogLSBWeight(HAL_AnalogInputHandle analogPortHandle, * * Volts = ((LSB_Weight * 1e-9) * raw) - (Offset * 1e-9) * - * @param analogPortHandle Handle to the analog port to use. + * @param[in] analogPortHandle Handle to the analog port to use. + * @param[out] status Error status variable. 0 on success. * @return Offset constant. */ int32_t HAL_GetAnalogOffset(HAL_AnalogInputHandle analogPortHandle, @@ -236,9 +250,11 @@ int32_t HAL_GetAnalogOffset(HAL_AnalogInputHandle analogPortHandle, /** * Get the analog voltage from a raw value. * - * @param analogPortHandle Handle to the analog port the values were read from. - * @param rawValue The raw analog value - * @return The voltage relating to the value + * @param[in] analogPortHandle Handle to the analog port the values were read + * from. + * @param[in] rawValue The raw analog value + * @param[out] status Error status variable. 0 on success. + * @return The voltage relating to the value */ double HAL_GetAnalogValueToVolts(HAL_AnalogInputHandle analogPortHandle, int32_t rawValue, int32_t* status); diff --git a/hal/src/main/native/include/hal/AnalogOutput.h b/hal/src/main/native/include/hal/AnalogOutput.h index ef013af95e..26e52318f5 100644 --- a/hal/src/main/native/include/hal/AnalogOutput.h +++ b/hal/src/main/native/include/hal/AnalogOutput.h @@ -21,10 +21,11 @@ extern "C" { /** * Initializes the analog output port using the given port object. * - * @param handle handle to the port - * @param allocationLocation the location where the allocation is occuring - * (can be null) - * @return the created analog output handle + * @param[in] portHandle handle to the port + * @param[in] allocationLocation the location where the allocation is occuring + * (can be null) + * @param[out] status Error status variable. 0 on success. + * @return the created analog output handle */ HAL_AnalogOutputHandle HAL_InitializeAnalogOutputPort( HAL_PortHandle portHandle, const char* allocationLocation, int32_t* status); @@ -39,8 +40,9 @@ void HAL_FreeAnalogOutputPort(HAL_AnalogOutputHandle analogOutputHandle); /** * Sets an analog output value. * - * @param analogOutputHandle the analog output handle - * @param voltage the voltage (0-5v) to output + * @param[in] analogOutputHandle the analog output handle + * @param[in] voltage the voltage (0-5v) to output + * @param[out] status Error status variable. 0 on success. */ void HAL_SetAnalogOutput(HAL_AnalogOutputHandle analogOutputHandle, double voltage, int32_t* status); @@ -48,8 +50,9 @@ void HAL_SetAnalogOutput(HAL_AnalogOutputHandle analogOutputHandle, /** * Gets the current analog output value. * - * @param analogOutputHandle the analog output handle - * @return the current output voltage (0-5v) + * @param[in] analogOutputHandle the analog output handle + * @param[out] status Error status variable. 0 on success. + * @return the current output voltage (0-5v) */ double HAL_GetAnalogOutput(HAL_AnalogOutputHandle analogOutputHandle, int32_t* status); diff --git a/hal/src/main/native/include/hal/AnalogTrigger.h b/hal/src/main/native/include/hal/AnalogTrigger.h index 3ed9840f0e..72727a8fca 100644 --- a/hal/src/main/native/include/hal/AnalogTrigger.h +++ b/hal/src/main/native/include/hal/AnalogTrigger.h @@ -33,8 +33,9 @@ extern "C" { /** * Initializes an analog trigger. * - * @param portHandle the analog input to use for triggering - * @return the created analog trigger handle + * @param[in] portHandle the analog input to use for triggering + * @param[out] status Error status variable. 0 on success. + * @return the created analog trigger handle */ HAL_AnalogTriggerHandle HAL_InitializeAnalogTrigger( HAL_AnalogInputHandle portHandle, int32_t* status); @@ -42,6 +43,8 @@ HAL_AnalogTriggerHandle HAL_InitializeAnalogTrigger( /** * Initializes an analog trigger with a Duty Cycle input * + * @param[in] dutyCycleHandle the analog input to use for duty cycle + * @param[out] status Error status variable. 0 on success. */ HAL_AnalogTriggerHandle HAL_InitializeAnalogTriggerDutyCycle( HAL_DutyCycleHandle dutyCycleHandle, int32_t* status); @@ -49,7 +52,8 @@ HAL_AnalogTriggerHandle HAL_InitializeAnalogTriggerDutyCycle( /** * Frees an analog trigger. * - * @param analogTriggerHandle the trigger handle + * @param[in] analogTriggerHandle the trigger handle + * @param[out] status Error status variable. 0 on success. */ void HAL_CleanAnalogTrigger(HAL_AnalogTriggerHandle analogTriggerHandle, int32_t* status); @@ -60,9 +64,10 @@ void HAL_CleanAnalogTrigger(HAL_AnalogTriggerHandle analogTriggerHandle, * HAL_SetAnalogTriggerLimitsVoltage or HAL_SetAnalogTriggerLimitsDutyCycle * is likely better in most cases. * - * @param analogTriggerHandle the trigger handle - * @param lower the lower ADC value - * @param upper the upper ADC value + * @param[in] analogTriggerHandle the trigger handle + * @param[in] lower the lower ADC value + * @param[in] upper the upper ADC value + * @param[out] status Error status variable. 0 on success. */ void HAL_SetAnalogTriggerLimitsRaw(HAL_AnalogTriggerHandle analogTriggerHandle, int32_t lower, int32_t upper, @@ -73,14 +78,25 @@ void HAL_SetAnalogTriggerLimitsRaw(HAL_AnalogTriggerHandle analogTriggerHandle, * * The limits are given as floating point voltage values. * - * @param analogTriggerHandle the trigger handle - * @param lower the lower voltage value - * @param upper the upper voltage value + * @param[in] analogTriggerHandle the trigger handle + * @param[in] lower the lower voltage value + * @param[in] upper the upper voltage value + * @param[out] status Error status variable. 0 on success. */ void HAL_SetAnalogTriggerLimitsVoltage( HAL_AnalogTriggerHandle analogTriggerHandle, double lower, double upper, int32_t* status); +/** + * Sets the upper and lower limits of the analog trigger. + * + * The limits are given as floating point duty cycle values. + * + * @param[in] analogTriggerHandle the trigger handle + * @param[in] lower the lower duty cycle value + * @param[in] upper the upper duty cycle value + * @param[out] status Error status variable. 0 on success. + */ void HAL_SetAnalogTriggerLimitsDutyCycle( HAL_AnalogTriggerHandle analogTriggerHandle, double lower, double upper, int32_t* status); @@ -94,8 +110,9 @@ void HAL_SetAnalogTriggerLimitsDutyCycle( * This is not allowed to be used if filtered mode is set. * This is not allowed to be used with Duty Cycle based inputs. * - * @param analogTriggerHandle the trigger handle - * @param useAveragedValue true to use averaged values, false for raw + * @param[in] analogTriggerHandle the trigger handle + * @param[in] useAveragedValue true to use averaged values, false for raw + * @param[out] status Error status variable. 0 on success. */ void HAL_SetAnalogTriggerAveraged(HAL_AnalogTriggerHandle analogTriggerHandle, HAL_Bool useAveragedValue, int32_t* status); @@ -109,9 +126,10 @@ void HAL_SetAnalogTriggerAveraged(HAL_AnalogTriggerHandle analogTriggerHandle, * * This is not allowed to be used if averaged mode is set. * - * @param analogTriggerHandle the trigger handle - * @param useFilteredValue true to use filtered values, false for average or - * raw + * @param[in] analogTriggerHandle the trigger handle + * @param[in] useFilteredValue true to use filtered values, false for average + * or raw + * @param[out] status Error status variable. 0 on success. */ void HAL_SetAnalogTriggerFiltered(HAL_AnalogTriggerHandle analogTriggerHandle, HAL_Bool useFilteredValue, int32_t* status); @@ -121,8 +139,9 @@ void HAL_SetAnalogTriggerFiltered(HAL_AnalogTriggerHandle analogTriggerHandle, * * True if the analog input is between the upper and lower limits. * - * @param analogTriggerHandle the trigger handle - * @return the InWindow output of the analog trigger + * @param[in] analogTriggerHandle the trigger handle + * @param[out] status Error status variable. 0 on success. + * @return the InWindow output of the analog trigger */ HAL_Bool HAL_GetAnalogTriggerInWindow( HAL_AnalogTriggerHandle analogTriggerHandle, int32_t* status); @@ -134,8 +153,9 @@ HAL_Bool HAL_GetAnalogTriggerInWindow( * False if below lower limit. * If in Hysteresis, maintain previous state. * - * @param analogTriggerHandle the trigger handle - * @return the TriggerState output of the analog trigger + * @param[in] analogTriggerHandle the trigger handle + * @param[out] status Error status variable. 0 on success. + * @return the TriggerState output of the analog trigger */ HAL_Bool HAL_GetAnalogTriggerTriggerState( HAL_AnalogTriggerHandle analogTriggerHandle, int32_t* status); @@ -143,9 +163,10 @@ HAL_Bool HAL_GetAnalogTriggerTriggerState( /** * Gets the state of the analog trigger output. * - * @param analogTriggerHandle the trigger handle - * @param type the type of trigger to trigger on - * @return the state of the analog trigger output + * @param[in] analogTriggerHandle the trigger handle + * @param[in] type the type of trigger to trigger on + * @param[out] status Error status variable. 0 on success. + * @return the state of the analog trigger output */ HAL_Bool HAL_GetAnalogTriggerOutput(HAL_AnalogTriggerHandle analogTriggerHandle, HAL_AnalogTriggerType type, @@ -154,7 +175,8 @@ HAL_Bool HAL_GetAnalogTriggerOutput(HAL_AnalogTriggerHandle analogTriggerHandle, /** * Get the FPGA index for the AnlogTrigger. * - * @param analogTriggerHandle the trigger handle + * @param[in] analogTriggerHandle the trigger handle + * @param[out] status Error status variable. 0 on success. * @return the FPGA index */ int32_t HAL_GetAnalogTriggerFPGAIndex( diff --git a/hal/src/main/native/include/hal/CAN.h b/hal/src/main/native/include/hal/CAN.h index aee8e33ba4..77a6239d6e 100644 --- a/hal/src/main/native/include/hal/CAN.h +++ b/hal/src/main/native/include/hal/CAN.h @@ -45,11 +45,12 @@ extern "C" { /** * Sends a CAN message. * - * @param messageID the CAN ID to send - * @param data the data to send (0-8 bytes) - * @param dataSize the size of the data to send (0-8 bytes) - * @param periodMs the period to repeat the packet at. Use - * HAL_CAN_SEND_PERIOD_NO_REPEAT to not repeat. + * @param[in] messageID the CAN ID to send + * @param[in] data the data to send (0-8 bytes) + * @param[in] dataSize the size of the data to send (0-8 bytes) + * @param[in] periodMs the period to repeat the packet at. Use + * HAL_CAN_SEND_PERIOD_NO_REPEAT to not repeat. + * @param[out] status Error status variable. 0 on success. */ void HAL_CAN_SendMessage(uint32_t messageID, const uint8_t* data, uint8_t dataSize, int32_t periodMs, int32_t* status); @@ -57,12 +58,13 @@ void HAL_CAN_SendMessage(uint32_t messageID, const uint8_t* data, /** * Receives a CAN message. * - * @param messageID store for the received message ID - * @param messageIDMask the message ID mask to look for - * @param data data output (8 bytes) - * @param dataSize data length (0-8 bytes) - * @param timeStamp the packet received timestamp (based off of - * CLOCK_MONOTONIC) + * @param[out] messageID store for the received message ID + * @param[in] messageIDMask the message ID mask to look for + * @param[out] data data output (8 bytes) + * @param[out] dataSize data length (0-8 bytes) + * @param[out] timeStamp the packet received timestamp (based off of + * CLOCK_MONOTONIC) + * @param[out] status Error status variable. 0 on success. */ void HAL_CAN_ReceiveMessage(uint32_t* messageID, uint32_t messageIDMask, uint8_t* data, uint8_t* dataSize, @@ -71,10 +73,11 @@ void HAL_CAN_ReceiveMessage(uint32_t* messageID, uint32_t messageIDMask, /** * Opens a CAN stream. * - * @param sessionHandle output for the session handle - * @param messageID the message ID to read - * @param messageIDMask the mssage ID mask - * @param maxMessages the maximum number of messages to stream + * @param[out] sessionHandle output for the session handle + * @param[in] messageID the message ID to read + * @param[in] messageIDMask the mssage ID mask + * @param[in] maxMessages the maximum number of messages to stream + * @param[out] status Error status variable. 0 on success. */ void HAL_CAN_OpenStreamSession(uint32_t* sessionHandle, uint32_t messageID, uint32_t messageIDMask, uint32_t maxMessages, @@ -90,10 +93,11 @@ void HAL_CAN_CloseStreamSession(uint32_t sessionHandle); /** * Reads a CAN stream message. * - * @param sessionHandle the session handle - * @param messages array of messages - * @param messagesToRead the max number of messages to read - * @param messageRead the number of messages actually read + * @param[in] sessionHandle the session handle + * @param[in] messages array of messages + * @param[in] messagesToRead the max number of messages to read + * @param[out] messagesRead the number of messages actually read + * @param[out] status Error status variable. 0 on success. */ void HAL_CAN_ReadStreamSession(uint32_t sessionHandle, struct HAL_CANStreamMessage* messages, @@ -103,11 +107,12 @@ void HAL_CAN_ReadStreamSession(uint32_t sessionHandle, /** * Gets CAN status information. * - * @param percentBusUtilization the bus utilization - * @param busOffCount the number of bus off errors - * @param txFullCount the number of tx full errors - * @param receiveErrorCount the number of receive errors - * @param transmitErrorCount the number of transmit errors + * @param[out] percentBusUtilization the bus utilization + * @param[out] busOffCount the number of bus off errors + * @param[out] txFullCount the number of tx full errors + * @param[out] receiveErrorCount the number of receive errors + * @param[out] transmitErrorCount the number of transmit errors + * @param[out] status Error status variable. 0 on success. */ void HAL_CAN_GetCANStatus(float* percentBusUtilization, uint32_t* busOffCount, uint32_t* txFullCount, uint32_t* receiveErrorCount, diff --git a/hal/src/main/native/include/hal/CANAPI.h b/hal/src/main/native/include/hal/CANAPI.h index d410aa4926..29859cfd57 100644 --- a/hal/src/main/native/include/hal/CANAPI.h +++ b/hal/src/main/native/include/hal/CANAPI.h @@ -24,10 +24,11 @@ extern "C" { * * These follow the FIRST standard CAN layout. Link TBD * - * @param manufacturer the can manufacturer - * @param deviceId the device ID (0-63) - * @param deviceType the device type - * @return the created CAN handle + * @param[in] manufacturer the can manufacturer + * @param[in] deviceId the device ID (0-63) + * @param[in] deviceType the device type + * @param[out] status Error status variable. 0 on success. + * @return the created CAN handle */ HAL_CANHandle HAL_InitializeCAN(HAL_CANManufacturer manufacturer, int32_t deviceId, HAL_CANDeviceType deviceType, @@ -45,10 +46,11 @@ void HAL_CleanCAN(HAL_CANHandle handle); * * This ID is 10 bits. * - * @param handle the CAN handle - * @param data the data to write (0-8 bytes) - * @param length the length of data (0-8) - * @param apiId the ID to write (0-1023 bits) + * @param[in] handle the CAN handle + * @param[in] data the data to write (0-8 bytes) + * @param[in] length the length of data (0-8) + * @param[in] apiId the ID to write (0-1023 bits) + * @param[out] status Error status variable. 0 on success. */ void HAL_WriteCANPacket(HAL_CANHandle handle, const uint8_t* data, int32_t length, int32_t apiId, int32_t* status); @@ -60,11 +62,12 @@ void HAL_WriteCANPacket(HAL_CANHandle handle, const uint8_t* data, * * The RoboRIO will automatically repeat the packet at the specified interval * - * @param handle the CAN handle - * @param data the data to write (0-8 bytes) - * @param length the length of data (0-8) - * @param apiId the ID to write (0-1023) - * @param repeatMs the period to repeat in ms + * @param[in] handle the CAN handle + * @param[in] data the data to write (0-8 bytes) + * @param[in] length the length of data (0-8) + * @param[in] apiId the ID to write (0-1023) + * @param[in] repeatMs the period to repeat in ms + * @param[out] status Error status variable. 0 on success. */ void HAL_WriteCANPacketRepeating(HAL_CANHandle handle, const uint8_t* data, int32_t length, int32_t apiId, @@ -77,9 +80,10 @@ void HAL_WriteCANPacketRepeating(HAL_CANHandle handle, const uint8_t* data, * By spec, the length must be equal to the length sent by the other device, * otherwise behavior is unspecified. * - * @param handle the CAN handle - * @param length the length of data to request (0-8) - * @param apiId the ID to write (0-1023) + * @param[in] handle the CAN handle + * @param[in] length the length of data to request (0-8) + * @param[in] apiId the ID to write (0-1023) + * @param[out] status Error status variable. 0 on success. */ void HAL_WriteCANRTRFrame(HAL_CANHandle handle, int32_t length, int32_t apiId, int32_t* status); @@ -89,8 +93,9 @@ void HAL_WriteCANRTRFrame(HAL_CANHandle handle, int32_t length, int32_t apiId, * * This ID is 10 bits. * - * @param handle the CAN handle - * @param apiId the ID to stop repeating (0-1023) + * @param[in] handle the CAN handle + * @param[in] apiId the ID to stop repeating (0-1023) + * @param[out] status Error status variable. 0 on success. */ void HAL_StopCANPacketRepeating(HAL_CANHandle handle, int32_t apiId, int32_t* status); @@ -101,12 +106,13 @@ void HAL_StopCANPacketRepeating(HAL_CANHandle handle, int32_t apiId, * This will only return properly once per packet received. Multiple calls * without receiving another packet will return an error code. * - * @param handle the CAN handle - * @param apiId the ID to read (0-1023) - * @param data the packet data (8 bytes) - * @param length the received length (0-8 bytes) - * @param receivedTimestamp the packet received timestamp (based off of - * CLOCK_MONOTONIC) + * @param[in] handle the CAN handle + * @param[in] apiId the ID to read (0-1023) + * @param[out] data the packet data (8 bytes) + * @param[out] length the received length (0-8 bytes) + * @param[out] receivedTimestamp the packet received timestamp (based off of + * CLOCK_MONOTONIC) + * @param[out] status Error status variable. 0 on success. */ void HAL_ReadCANPacketNew(HAL_CANHandle handle, int32_t apiId, uint8_t* data, int32_t* length, uint64_t* receivedTimestamp, @@ -116,12 +122,13 @@ void HAL_ReadCANPacketNew(HAL_CANHandle handle, int32_t apiId, uint8_t* data, * Reads a CAN packet. The will continuously return the last packet received, * without accounting for packet age. * - * @param handle the CAN handle - * @param apiId the ID to read (0-1023) - * @param data the packet data (8 bytes) - * @param length the received length (0-8 bytes) - * @param receivedTimestamp the packet received timestamp (based off of - * CLOCK_MONOTONIC) + * @param[in] handle the CAN handle + * @param[in] apiId the ID to read (0-1023) + * @param[out] data the packet data (8 bytes) + * @param[out] length the received length (0-8 bytes) + * @param[out] receivedTimestamp the packet received timestamp (based off of + * CLOCK_MONOTONIC) + * @param[out] status Error status variable. 0 on success. */ void HAL_ReadCANPacketLatest(HAL_CANHandle handle, int32_t apiId, uint8_t* data, int32_t* length, uint64_t* receivedTimestamp, @@ -132,13 +139,14 @@ void HAL_ReadCANPacketLatest(HAL_CANHandle handle, int32_t apiId, uint8_t* data, * packet is older then the requested timeout. Then it will return an error * code. * - * @param handle the CAN handle - * @param apiId the ID to read (0-1023) - * @param data the packet data (8 bytes) - * @param length the received length (0-8 bytes) - * @param receivedTimestamp the packet received timestamp (based off of - * CLOCK_MONOTONIC) - * @param timeoutMs the timeout time for the packet + * @param[in] handle the CAN handle + * @param[in] apiId the ID to read (0-1023) + * @param[out] data the packet data (8 bytes) + * @param[out] length the received length (0-8 bytes) + * @param[out] receivedTimestamp the packet received timestamp (based off of + * CLOCK_MONOTONIC) + * @param[out] timeoutMs the timeout time for the packet + * @param[out] status Error status variable. 0 on success. */ void HAL_ReadCANPacketTimeout(HAL_CANHandle handle, int32_t apiId, uint8_t* data, int32_t* length, diff --git a/hal/src/main/native/include/hal/Counter.h b/hal/src/main/native/include/hal/Counter.h index df681062e7..cc2d77692a 100644 --- a/hal/src/main/native/include/hal/Counter.h +++ b/hal/src/main/native/include/hal/Counter.h @@ -34,9 +34,10 @@ extern "C" { /** * Initializes a counter. * - * @param mode the counter mode - * @param index the compressor index (output) - * @return the created handle + * @param[in] mode the counter mode + * @param[in] index the compressor index (output) + * @param[out] status Error status variable. 0 on success. + * @return the created handle */ HAL_CounterHandle HAL_InitializeCounter(HAL_Counter_Mode mode, int32_t* index, int32_t* status); @@ -44,15 +45,17 @@ HAL_CounterHandle HAL_InitializeCounter(HAL_Counter_Mode mode, int32_t* index, /** * Frees a counter. * - * @param counterHandle the counter handle + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. */ void HAL_FreeCounter(HAL_CounterHandle counterHandle, int32_t* status); /** * Sets the average sample size of a counter. * - * @param counterHandle the counter handle - * @param size the size of samples to average + * @param[in] counterHandle the counter handle + * @param[in] size the size of samples to average + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterAverageSize(HAL_CounterHandle counterHandle, int32_t size, int32_t* status); @@ -60,11 +63,13 @@ void HAL_SetCounterAverageSize(HAL_CounterHandle counterHandle, int32_t size, /** * Sets the source object that causes the counter to count up. * - * @param counterHandle the counter handle - * @param digitalSourceHandle the digital source handle (either a - * HAL_AnalogTriggerHandle or a HAL_DigitalHandle) - * @param analogTriggerType the analog trigger type if the source is an analog - * trigger + * @param[in] counterHandle the counter handle + * @param[in] digitalSourceHandle the digital source handle (either a + * HAL_AnalogTriggerHandle or a + * HAL_DigitalHandle) + * @param[in] analogTriggerType the analog trigger type if the source is an + * analog trigger + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterUpSource(HAL_CounterHandle counterHandle, HAL_Handle digitalSourceHandle, @@ -76,9 +81,10 @@ void HAL_SetCounterUpSource(HAL_CounterHandle counterHandle, * * Note that both are allowed to be set true at the same time without issues. * - * @param counterHandle the counter handle - * @param risingEdge true to trigger on rising - * @param fallingEdge true to trigger on falling + * @param[in] counterHandle the counter handle + * @param[in] risingEdge true to trigger on rising + * @param[in] fallingEdge true to trigger on falling + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterUpSourceEdge(HAL_CounterHandle counterHandle, HAL_Bool risingEdge, HAL_Bool fallingEdge, @@ -87,18 +93,21 @@ void HAL_SetCounterUpSourceEdge(HAL_CounterHandle counterHandle, /** * Disables the up counting source to the counter. * - * @param counterHandle the counter handle + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. */ void HAL_ClearCounterUpSource(HAL_CounterHandle counterHandle, int32_t* status); /** * Sets the source object that causes the counter to count down. * - * @param counterHandle the counter handle - * @param digitalSourceHandle the digital source handle (either a - * HAL_AnalogTriggerHandle or a HAL_DigitalHandle) - * @param analogTriggerType the analog trigger type if the source is an analog - * trigger + * @param[in] counterHandle the counter handle + * @param[in] digitalSourceHandle the digital source handle (either a + * HAL_AnalogTriggerHandle or a + * HAL_DigitalHandle) + * @param[in] analogTriggerType the analog trigger type if the source is an + * analog trigger + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterDownSource(HAL_CounterHandle counterHandle, HAL_Handle digitalSourceHandle, @@ -109,9 +118,10 @@ void HAL_SetCounterDownSource(HAL_CounterHandle counterHandle, * Sets the down source to either detect rising edges or falling edges. * Note that both are allowed to be set true at the same time without issues. * - * @param counterHandle the counter handle - * @param risingEdge true to trigger on rising - * @param fallingEdge true to trigger on falling + * @param[in] counterHandle the counter handle + * @param[in] risingEdge true to trigger on rising + * @param[in] fallingEdge true to trigger on falling + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterDownSourceEdge(HAL_CounterHandle counterHandle, HAL_Bool risingEdge, HAL_Bool fallingEdge, @@ -120,7 +130,8 @@ void HAL_SetCounterDownSourceEdge(HAL_CounterHandle counterHandle, /** * Disables the down counting source to the counter. * - * @param counterHandle the counter handle + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. */ void HAL_ClearCounterDownSource(HAL_CounterHandle counterHandle, int32_t* status); @@ -130,7 +141,8 @@ void HAL_ClearCounterDownSource(HAL_CounterHandle counterHandle, * * Up and down counts are sourced independently from two inputs. * - * @param counterHandle the counter handle + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterUpDownMode(HAL_CounterHandle counterHandle, int32_t* status); @@ -140,7 +152,8 @@ void HAL_SetCounterUpDownMode(HAL_CounterHandle counterHandle, int32_t* status); * The direction is determined by the B input, with counting happening with the * A input. * - * @param counterHandle the counter handle + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterExternalDirectionMode(HAL_CounterHandle counterHandle, int32_t* status); @@ -151,8 +164,10 @@ void HAL_SetCounterExternalDirectionMode(HAL_CounterHandle counterHandle, * The counter counts up based on the time the input is triggered. High or Low * depends on the highSemiPeriod parameter. * - * @param counterHandle the counter handle - * @param highSemiPeriod true for counting when the input is high, false for low + * @param[in] counterHandle the counter handle + * @param[in] highSemiPeriod true for counting when the input is high, false for + * low + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterSemiPeriodMode(HAL_CounterHandle counterHandle, HAL_Bool highSemiPeriod, int32_t* status); @@ -163,9 +178,10 @@ void HAL_SetCounterSemiPeriodMode(HAL_CounterHandle counterHandle, * * This mode is most useful for direction sensitive gear tooth sensors. * - * @param counterHandle the counter handle - * @param threshold The pulse length beyond which the counter counts the - * opposite direction (seconds) + * @param[in] counterHandle the counter handle + * @param[in] threshold The pulse length beyond which the counter counts the + * opposite direction (seconds) + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterPulseLengthMode(HAL_CounterHandle counterHandle, double threshold, int32_t* status); @@ -175,7 +191,8 @@ void HAL_SetCounterPulseLengthMode(HAL_CounterHandle counterHandle, * timer to average when calculating the period. Perform averaging to account * for mechanical imperfections or as oversampling to increase resolution. * - * @param counterHandle the counter handle + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. * @return SamplesToAverage The number of samples being averaged (from 1 to 127) */ int32_t HAL_GetCounterSamplesToAverage(HAL_CounterHandle counterHandle, @@ -186,8 +203,9 @@ int32_t HAL_GetCounterSamplesToAverage(HAL_CounterHandle counterHandle, * timer to average when calculating the period. Perform averaging to account * for mechanical imperfections or as oversampling to increase resolution. * - * @param counterHandle the counter handle - * @param samplesToAverage The number of samples to average from 1 to 127 + * @param[in] counterHandle the counter handle + * @param[in] samplesToAverage The number of samples to average from 1 to 127 + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterSamplesToAverage(HAL_CounterHandle counterHandle, int32_t samplesToAverage, int32_t* status); @@ -198,7 +216,8 @@ void HAL_SetCounterSamplesToAverage(HAL_CounterHandle counterHandle, * Sets the counter value to zero. This does not effect the running state of the * counter, just sets the current value to zero. * - * @param counterHandle the counter handle + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. */ void HAL_ResetCounter(HAL_CounterHandle counterHandle, int32_t* status); @@ -208,8 +227,9 @@ void HAL_ResetCounter(HAL_CounterHandle counterHandle, int32_t* status); * Reads the value at this instant. It may still be running, so it reflects the * current value. Next time it is read, it might have a different value. * - * @param counterHandle the counter handle - * @return the current counter value + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. + * @return the current counter value */ int32_t HAL_GetCounter(HAL_CounterHandle counterHandle, int32_t* status); @@ -219,8 +239,9 @@ int32_t HAL_GetCounter(HAL_CounterHandle counterHandle, int32_t* status); * Returns the time interval of the most recent count. This can be used for * velocity calculations to determine shaft speed. * - * @param counterHandle the counter handle - * @returns the period of the last two pulses in units of seconds + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. + * @return the period of the last two pulses in units of seconds */ double HAL_GetCounterPeriod(HAL_CounterHandle counterHandle, int32_t* status); @@ -231,9 +252,10 @@ double HAL_GetCounterPeriod(HAL_CounterHandle counterHandle, int32_t* status); * used to determine the "stopped" state of the counter using the * HAL_GetCounterStopped method. * - * @param counterHandle the counter handle - * @param maxPeriod the maximum period where the counted device is - * considered moving in seconds + * @param[in] counterHandle the counter handle + * @param[in] maxPeriod the maximum period where the counted device is + * considered moving in seconds + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterMaxPeriod(HAL_CounterHandle counterHandle, double maxPeriod, int32_t* status); @@ -258,8 +280,9 @@ void HAL_SetCounterMaxPeriod(HAL_CounterHandle counterHandle, double maxPeriod, * (since it is updated at the end of an average and there are no samples to * average). * - * @param counterHandle the counter handle - * @param enabled true to enable counter updating with no samples + * @param[in] counterHandle the counter handle + * @param[in] enabled true to enable counter updating with no samples + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterUpdateWhenEmpty(HAL_CounterHandle counterHandle, HAL_Bool enabled, int32_t* status); @@ -271,9 +294,10 @@ void HAL_SetCounterUpdateWhenEmpty(HAL_CounterHandle counterHandle, * using the SetMaxPeriod method. If the clock exceeds the MaxPeriod, then the * device (and counter) are assumed to be stopped and it returns true. * - * @param counterHandle the counter handle - * @return true if the most recent counter period exceeds the - * MaxPeriod value set by SetMaxPeriod + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. + * @return true if the most recent counter period exceeds the MaxPeriod value + * set by SetMaxPeriod */ HAL_Bool HAL_GetCounterStopped(HAL_CounterHandle counterHandle, int32_t* status); @@ -281,8 +305,9 @@ HAL_Bool HAL_GetCounterStopped(HAL_CounterHandle counterHandle, /** * Gets the last direction the counter value changed. * - * @param counterHandle the counter handle - * @return the last direction the counter value changed + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. + * @return the last direction the counter value changed */ HAL_Bool HAL_GetCounterDirection(HAL_CounterHandle counterHandle, int32_t* status); @@ -293,8 +318,9 @@ HAL_Bool HAL_GetCounterDirection(HAL_CounterHandle counterHandle, * This allows counters to change the direction they are counting in the case of * 1X and 2X quadrature encoding only. Any other counter mode isn't supported. * - * @param counterHandle the counter handle - * @param reverseDirection true if the value counted should be negated. + * @param[in] counterHandle the counter handle + * @param[in] reverseDirection true if the value counted should be negated. + * @param[out] status Error status variable. 0 on success. */ void HAL_SetCounterReverseDirection(HAL_CounterHandle counterHandle, HAL_Bool reverseDirection, int32_t* status); diff --git a/hal/src/main/native/include/hal/DIO.h b/hal/src/main/native/include/hal/DIO.h index 0f25192fbd..e094a0d15c 100644 --- a/hal/src/main/native/include/hal/DIO.h +++ b/hal/src/main/native/include/hal/DIO.h @@ -21,11 +21,12 @@ extern "C" { /** * Creates a new instance of a digital port. * - * @param portHandle the port handle to create from - * @param input true for input, false for output - * @param allocationLocation the location where the allocation is occuring - * (can be null) - * @return the created digital handle + * @param[in] portHandle the port handle to create from + * @param[in] input true for input, false for output + * @param[in] allocationLocation the location where the allocation is occuring + * (can be null) + * @param[out] status Error status variable. 0 on success. + * @return the created digital handle */ HAL_DigitalHandle HAL_InitializeDIOPort(HAL_PortHandle portHandle, HAL_Bool input, @@ -36,14 +37,14 @@ HAL_DigitalHandle HAL_InitializeDIOPort(HAL_PortHandle portHandle, * Checks if a DIO channel is valid. * * @param channel the channel number to check - * @return true if the channel is correct, otherwise false + * @return true if the channel is correct, otherwise false */ HAL_Bool HAL_CheckDIOChannel(int32_t channel); /** * Frees a DIO port. * - * @param handle the DIO channel handle + * @param dioPortHandle the DIO channel handle */ void HAL_FreeDIOPort(HAL_DigitalHandle dioPortHandle); @@ -58,6 +59,7 @@ void HAL_SetDIOSimDevice(HAL_DigitalHandle handle, HAL_SimDeviceHandle device); /** * Allocates a DO PWM Generator. * + * @param[out] status Error status variable. 0 on success. * @return the allocated digital PWM handle */ HAL_DigitalPWMHandle HAL_AllocateDigitalPWM(int32_t* status); @@ -65,7 +67,8 @@ HAL_DigitalPWMHandle HAL_AllocateDigitalPWM(int32_t* status); /** * Frees the resource associated with a DO PWM generator. * - * @param pwmGenerator the digital PWM handle + * @param[in] pwmGenerator the digital PWM handle + * @param[out] status Error status variable. 0 on success. */ void HAL_FreeDigitalPWM(HAL_DigitalPWMHandle pwmGenerator, int32_t* status); @@ -76,15 +79,17 @@ void HAL_FreeDigitalPWM(HAL_DigitalPWMHandle pwmGenerator, int32_t* status); * * The frequency resolution is logarithmic. * - * @param rate the frequency to output all digital output PWM signals + * @param[in] rate the frequency to output all digital output PWM signals + * @param[out] status Error status variable. 0 on success. */ void HAL_SetDigitalPWMRate(double rate, int32_t* status); /** * Configures the duty-cycle of the PWM generator. * - * @param pwmGenerator the digital PWM handle - * @param dutyCycle the percent duty cycle to output [0..1] + * @param[in] pwmGenerator the digital PWM handle + * @param[in] dutyCycle the percent duty cycle to output [0..1] + * @param[out] status Error status variable. 0 on success. */ void HAL_SetDigitalPWMDutyCycle(HAL_DigitalPWMHandle pwmGenerator, double dutyCycle, int32_t* status); @@ -92,8 +97,9 @@ void HAL_SetDigitalPWMDutyCycle(HAL_DigitalPWMHandle pwmGenerator, /** * Configures which DO channel the PWM signal is output on. * - * @param pwmGenerator the digital PWM handle - * @param channel the channel to output on + * @param[in] pwmGenerator the digital PWM handle + * @param[in] channel the channel to output on + * @param[out] status Error status variable. 0 on success. */ void HAL_SetDigitalPWMOutputChannel(HAL_DigitalPWMHandle pwmGenerator, int32_t channel, int32_t* status); @@ -101,9 +107,10 @@ void HAL_SetDigitalPWMOutputChannel(HAL_DigitalPWMHandle pwmGenerator, /** * Writes a digital value to a DIO channel. * - * @param dioPortHandle the digital port handle - * @param value the state to set the digital channel (if it is - * configured as an output) + * @param[in] dioPortHandle the digital port handle + * @param[in] value the state to set the digital channel (if it is + * configured as an output) + * @param[out] status Error status variable. 0 on success. */ void HAL_SetDIO(HAL_DigitalHandle dioPortHandle, HAL_Bool value, int32_t* status); @@ -111,8 +118,9 @@ void HAL_SetDIO(HAL_DigitalHandle dioPortHandle, HAL_Bool value, /** * Sets the direction of a DIO channel. * - * @param dioPortHandle the digital port handle - * @param input true to set input, false for output + * @param[in] dioPortHandle the digital port handle + * @param[in] input true to set input, false for output + * @param[out] status Error status variable. 0 on success. */ void HAL_SetDIODirection(HAL_DigitalHandle dioPortHandle, HAL_Bool input, int32_t* status); @@ -120,16 +128,18 @@ void HAL_SetDIODirection(HAL_DigitalHandle dioPortHandle, HAL_Bool input, /** * Reads a digital value from a DIO channel. * - * @param dioPortHandle the digital port handle - * @return the state of the specified channel + * @param[in] dioPortHandle the digital port handle + * @param[out] status Error status variable. 0 on success. + * @return the state of the specified channel */ HAL_Bool HAL_GetDIO(HAL_DigitalHandle dioPortHandle, int32_t* status); /** * Reads the direction of a DIO channel. * - * @param dioPortHandle the digital port handle - * @return true for input, false for output + * @param[in] dioPortHandle the digital port handle + * @param[out] status Error status variable. 0 on success. + * @return true for input, false for output */ HAL_Bool HAL_GetDIODirection(HAL_DigitalHandle dioPortHandle, int32_t* status); @@ -139,8 +149,9 @@ HAL_Bool HAL_GetDIODirection(HAL_DigitalHandle dioPortHandle, int32_t* status); * Write a pulse to the specified digital output channel. There can only be a * single pulse going at any time. * - * @param dioPortHandle the digital port handle - * @param pulseLength the active length of the pulse (in seconds) + * @param[in] dioPortHandle the digital port handle + * @param[in] pulseLength the active length of the pulse (in seconds) + * @param[out] status Error status variable. 0 on success. */ void HAL_Pulse(HAL_DigitalHandle dioPortHandle, double pulseLength, int32_t* status); @@ -148,6 +159,8 @@ void HAL_Pulse(HAL_DigitalHandle dioPortHandle, double pulseLength, /** * Checks a DIO line to see if it is currently generating a pulse. * + * @param[in] dioPortHandle the digital port handle + * @param[out] status Error status variable. 0 on success. * @return true if a pulse is in progress, otherwise false */ HAL_Bool HAL_IsPulsing(HAL_DigitalHandle dioPortHandle, int32_t* status); @@ -155,6 +168,7 @@ HAL_Bool HAL_IsPulsing(HAL_DigitalHandle dioPortHandle, int32_t* status); /** * Checks if any DIO line is currently generating a pulse. * + * @param[out] status Error status variable. 0 on success. * @return true if a pulse on some line is in progress */ HAL_Bool HAL_IsAnyPulsing(int32_t* status); @@ -164,9 +178,11 @@ HAL_Bool HAL_IsAnyPulsing(int32_t* status); * * Set the filter index used to filter out short pulses. * - * @param dioPortHandle the digital port handle - * @param filterIndex the filter index (Must be in the range 0 - 3, where 0 - * means "none" and 1 - 3 means filter # filterIndex - 1) + * @param[in] dioPortHandle the digital port handle + * @param[in] filterIndex the filter index (Must be in the range 0 - 3, where + * 0 means "none" and 1 - 3 means filter # filterIndex + * - 1) + * @param[out] status Error status variable. 0 on success. */ void HAL_SetFilterSelect(HAL_DigitalHandle dioPortHandle, int32_t filterIndex, int32_t* status); @@ -176,9 +192,10 @@ void HAL_SetFilterSelect(HAL_DigitalHandle dioPortHandle, int32_t filterIndex, * * Gets the filter index used to filter out short pulses. * - * @param dioPortHandle the digital port handle - * @return filterIndex the filter index (Must be in the range 0 - 3, - * where 0 means "none" and 1 - 3 means filter # filterIndex - 1) + * @param[in] dioPortHandle the digital port handle + * @param[out] status Error status variable. 0 on success. + * @return filterIndex the filter index (Must be in the range 0 - 3, where 0 + * means "none" and 1 - 3 means filter # filterIndex - 1) */ int32_t HAL_GetFilterSelect(HAL_DigitalHandle dioPortHandle, int32_t* status); @@ -189,9 +206,10 @@ int32_t HAL_GetFilterSelect(HAL_DigitalHandle dioPortHandle, int32_t* status); * filter index domains (MXP vs HDR), ignore that distinction for now since it * compilicates the interface. That can be changed later. * - * @param filterIndex the filter index, 0 - 2 - * @param value the number of cycles that the signal must not transition - * to be counted as a transition. + * @param[in] filterIndex the filter index, 0 - 2 + * @param[in] value the number of cycles that the signal must not + * transition to be counted as a transition. + * @param[out] status Error status variable. 0 on success. */ void HAL_SetFilterPeriod(int32_t filterIndex, int64_t value, int32_t* status); @@ -203,9 +221,8 @@ void HAL_SetFilterPeriod(int32_t filterIndex, int64_t value, int32_t* status); * compilicates the interface. Set status to NiFpga_Status_SoftwareFault if the * filter values miss-match. * - * @param filterIndex the filter index, 0 - 2 - * @param value the number of cycles that the signal must not transition - * to be counted as a transition. + * @param[in] filterIndex the filter index, 0 - 2 + * @param[out] status Error status variable. 0 on success. */ int64_t HAL_GetFilterPeriod(int32_t filterIndex, int32_t* status); #ifdef __cplusplus diff --git a/hal/src/main/native/include/hal/DMA.h b/hal/src/main/native/include/hal/DMA.h index 49eb017810..7610d9b8ba 100644 --- a/hal/src/main/native/include/hal/DMA.h +++ b/hal/src/main/native/include/hal/DMA.h @@ -42,6 +42,7 @@ extern "C" { /** * Initializes an object for peforming DMA transfers. * + * @param[out] status Error status variable. 0 on success. * @return the created dma handle */ HAL_DMAHandle HAL_InitializeDMA(int32_t* status); @@ -58,8 +59,9 @@ void HAL_FreeDMA(HAL_DMAHandle handle); * * This can only be called while DMA is running. * - * @param handle the dma handle - * @param pause true to pause transfers, false to resume. + * @param[in] handle the dma handle + * @param[in] pause true to pause transfers, false to resume. + * @param[out] status Error status variable. 0 on success. */ void HAL_SetDMAPause(HAL_DMAHandle handle, HAL_Bool pause, int32_t* status); @@ -72,8 +74,9 @@ void HAL_SetDMAPause(HAL_DMAHandle handle, HAL_Bool pause, int32_t* status); * * This can only be called if DMA is not started. * - * @param handle the dma handle - * @param periodSeconds the period to trigger in seconds + * @param[in] handle the dma handle + * @param[in] periodSeconds the period to trigger in seconds + * @param[out] status Error status variable. 0 on success. */ void HAL_SetDMATimedTrigger(HAL_DMAHandle handle, double periodSeconds, int32_t* status); @@ -91,8 +94,9 @@ void HAL_SetDMATimedTrigger(HAL_DMAHandle handle, double periodSeconds, * * This can only be called if DMA is not started. * - * @param handle the dma handle - * @param cycles the period to trigger in FPGA cycles + * @param[in] handle the dma handle + * @param[in] cycles the period to trigger in FPGA cycles + * @param[out] status Error status variable. 0 on success. */ void HAL_SetDMATimedTriggerCycles(HAL_DMAHandle handle, uint32_t cycles, int32_t* status); @@ -102,8 +106,9 @@ void HAL_SetDMATimedTriggerCycles(HAL_DMAHandle handle, uint32_t cycles, * * This can only be called if DMA is not started. * - * @param handle the dma handle - * @param encoderHandle the encoder to add + * @param[in] handle the dma handle + * @param[in] encoderHandle the encoder to add + * @param[out] status Error status variable. 0 on success. */ void HAL_AddDMAEncoder(HAL_DMAHandle handle, HAL_EncoderHandle encoderHandle, int32_t* status); @@ -113,8 +118,9 @@ void HAL_AddDMAEncoder(HAL_DMAHandle handle, HAL_EncoderHandle encoderHandle, * * This can only be called if DMA is not started. * - * @param handle the dma handle - * @param encoderHandle the encoder to add + * @param[in] handle the dma handle + * @param[in] encoderHandle the encoder to add + * @param[out] status Error status variable. 0 on success. */ void HAL_AddDMAEncoderPeriod(HAL_DMAHandle handle, HAL_EncoderHandle encoderHandle, int32_t* status); @@ -124,8 +130,9 @@ void HAL_AddDMAEncoderPeriod(HAL_DMAHandle handle, * * This can only be called if DMA is not started. * - * @param handle the dma handle - * @param counterHandle the counter to add + * @param[in] handle the dma handle + * @param[in] counterHandle the counter to add + * @param[out] status Error status variable. 0 on success. */ void HAL_AddDMACounter(HAL_DMAHandle handle, HAL_CounterHandle counterHandle, int32_t* status); @@ -133,8 +140,9 @@ void HAL_AddDMACounter(HAL_DMAHandle handle, HAL_CounterHandle counterHandle, /** * Adds timer data for an counter to be collected by DMA. * - * @param handle the dma handle - * @param counterHandle the counter to add + * @param[in] handle the dma handle + * @param[in] counterHandle the counter to add + * @param[out] status Error status variable. 0 on success. */ void HAL_AddDMACounterPeriod(HAL_DMAHandle handle, HAL_CounterHandle counterHandle, int32_t* status); @@ -144,8 +152,9 @@ void HAL_AddDMACounterPeriod(HAL_DMAHandle handle, * * This can only be called if DMA is not started. * - * @param handle the dma handle - * @param digitalSourceHandle the digital source to add + * @param[in] handle the dma handle + * @param[in] digitalSourceHandle the digital source to add + * @param[out] status Error status variable. 0 on success. */ void HAL_AddDMADigitalSource(HAL_DMAHandle handle, HAL_Handle digitalSourceHandle, int32_t* status); @@ -155,8 +164,9 @@ void HAL_AddDMADigitalSource(HAL_DMAHandle handle, * * This can only be called if DMA is not started. * - * @param handle the dma handle - * @param aInHandle the analog input to add + * @param[in] handle the dma handle + * @param[in] aInHandle the analog input to add + * @param[out] status Error status variable. 0 on success. */ void HAL_AddDMAAnalogInput(HAL_DMAHandle handle, HAL_AnalogInputHandle aInHandle, int32_t* status); @@ -166,8 +176,9 @@ void HAL_AddDMAAnalogInput(HAL_DMAHandle handle, * * This can only be called if DMA is not started. * - * @param handle the dma handle - * @param aInHandle the analog input to add + * @param[in] handle the dma handle + * @param[in] aInHandle the analog input to add + * @param[out] status Error status variable. 0 on success. */ void HAL_AddDMAAveragedAnalogInput(HAL_DMAHandle handle, HAL_AnalogInputHandle aInHandle, @@ -178,8 +189,9 @@ void HAL_AddDMAAveragedAnalogInput(HAL_DMAHandle handle, * * This can only be called if DMA is not started. * - * @param handle the dma handle - * @param aInHandle the analog input to add + * @param[in] handle the dma handle + * @param[in] aInHandle the analog input to add + * @param[out] status Error status variable. 0 on success. */ void HAL_AddDMAAnalogAccumulator(HAL_DMAHandle handle, HAL_AnalogInputHandle aInHandle, @@ -190,8 +202,9 @@ void HAL_AddDMAAnalogAccumulator(HAL_DMAHandle handle, * * This can only be called if DMA is not started. * - * @param handle the dma handle - * @param dutyCycleHandle the duty cycle input to add + * @param[in] handle the dma handle + * @param[in] dutyCycleHandle the duty cycle input to add + * @param[out] status Error status variable. 0 on success. */ void HAL_AddDMADutyCycle(HAL_DMAHandle handle, HAL_DutyCycleHandle dutyCycleHandle, int32_t* status); @@ -205,13 +218,15 @@ void HAL_AddDMADutyCycle(HAL_DMAHandle handle, * * This can only be called if DMA is not started. * - * @param handle the dma handle - * @param digitalSourceHandle the digital source handle (either a - * HAL_AnalogTriggerHandle or a HAL_DigitalHandle) - * @param analogTriggerType the analog trigger type if the source is an analog - * trigger - * @param risingEdge true to trigger on rising - * @param fallingEdge true to trigger on falling + * @param[in] handle the dma handle + * @param[in] digitalSourceHandle the digital source handle (either a + * HAL_AnalogTriggerHandle or a + * HAL_DigitalHandle) + * @param[in] analogTriggerType the analog trigger type if the source is an + * analog trigger + * @param[in] rising true to trigger on rising edge + * @param[in] falling true to trigger on falling edge + * @param[out] status Error status variable. 0 on success. * @return the index of the trigger */ int32_t HAL_SetDMAExternalTrigger(HAL_DMAHandle handle, @@ -225,7 +240,8 @@ int32_t HAL_SetDMAExternalTrigger(HAL_DMAHandle handle, * * This can only be called if DMA is not started. * - * @param handle the dma handle + * @param[in] handle the dma handle + * @param[out] status Error status variable. 0 on success. */ void HAL_ClearDMASensors(HAL_DMAHandle handle, int32_t* status); @@ -234,22 +250,25 @@ void HAL_ClearDMASensors(HAL_DMAHandle handle, int32_t* status); * * This can only be called if DMA is not started. * - * @param handle the dma handle + * @param[in] handle the dma handle + * @param[out] status Error status variable. 0 on success. */ void HAL_ClearDMAExternalTriggers(HAL_DMAHandle handle, int32_t* status); /** * Starts DMA Collection. * - * @param handle the dma handle - * @param queueDepth the number of objects to be able to queue + * @param[in] handle the dma handle + * @param[in] queueDepth the number of objects to be able to queue + * @param[out] status Error status variable. 0 on success. */ void HAL_StartDMA(HAL_DMAHandle handle, int32_t queueDepth, int32_t* status); /** * Stops DMA Collection. * - * @param handle the dma handle + * @param[in] handle the dma handle + * @param[out] status Error status variable. 0 on success. */ void HAL_StopDMA(HAL_DMAHandle handle, int32_t* status); @@ -268,7 +287,12 @@ void* HAL_GetDMADirectPointer(HAL_DMAHandle handle); * * See HAL_ReadDMA for full documentation. * - * @param handle the dma handle + * @param[in] dmaPointer direct DMA pointer + * @param[in] dmaSample the sample object to place data into + * @param[in] timeoutSeconds the time to wait for data to be queued before + * timing out + * @param[in] remainingOut the number of samples remaining in the queue + * @param[out] status Error status variable. 0 on success. */ enum HAL_DMAReadStatus HAL_ReadDMADirect(void* dmaPointer, HAL_DMASample* dmaSample, @@ -280,11 +304,12 @@ enum HAL_DMAReadStatus HAL_ReadDMADirect(void* dmaPointer, * Reads a DMA sample from the queue. * * - * @param handle the dma handle - * @param dmaSample the sample object to place data into - * @param timeoutSeconds the time to wait for data to be queued before timing - * out - * @param remainingOut the number of samples remaining in the queue + * @param[in] handle the dma handle + * @param[in] dmaSample the sample object to place data into + * @param[in] timeoutSeconds the time to wait for data to be queued before + * timing out + * @param[in] remainingOut the number of samples remaining in the queue + * @param[out] status Error status variable. 0 on success. * @return the succes result of the sample read */ enum HAL_DMAReadStatus HAL_ReadDMA(HAL_DMAHandle handle, @@ -298,7 +323,8 @@ enum HAL_DMAReadStatus HAL_ReadDMA(HAL_DMAHandle handle, * Returns the timestamp of the sample. * This is in the same time domain as HAL_GetFPGATime(). * - * @param dmaSample the sample to read from + * @param[in] dmaSample the sample to read from + * @param[out] status Error status variable. 0 on success. * @return timestamp in microseconds since FPGA Initialization */ uint64_t HAL_GetDMASampleTime(const HAL_DMASample* dmaSample, int32_t* status); @@ -309,8 +335,9 @@ uint64_t HAL_GetDMASampleTime(const HAL_DMASample* dmaSample, int32_t* status); * This can be scaled with DistancePerPulse and DecodingScaleFactor to match the * result of GetDistance() * - * @param dmaSample the sample to read from - * @param encoderHandle the encoder handle + * @param[in] dmaSample the sample to read from + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. * @return raw encoder ticks */ int32_t HAL_GetDMASampleEncoderRaw(const HAL_DMASample* dmaSample, @@ -320,8 +347,9 @@ int32_t HAL_GetDMASampleEncoderRaw(const HAL_DMASample* dmaSample, /** * Returns the distance data for an counter from the sample. * - * @param dmaSample the sample to read from - * @param counterHandle the counter handle + * @param[in] dmaSample the sample to read from + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. * @return counter ticks */ int32_t HAL_GetDMASampleCounter(const HAL_DMASample* dmaSample, @@ -334,8 +362,9 @@ int32_t HAL_GetDMASampleCounter(const HAL_DMASample* dmaSample, * This can be scaled with DistancePerPulse and DecodingScaleFactor to match the * result of GetRate() * - * @param dmaSample the sample to read from - * @param encoderHandle the encoder handle + * @param[in] dmaSample the sample to read from + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. * @return raw encoder period */ int32_t HAL_GetDMASampleEncoderPeriodRaw(const HAL_DMASample* dmaSample, @@ -345,8 +374,9 @@ int32_t HAL_GetDMASampleEncoderPeriodRaw(const HAL_DMASample* dmaSample, /** * Returns the period data for an counter from the sample. * - * @param dmaSample the sample to read from - * @param counterHandle the counter handle + * @param[in] dmaSample the sample to read from + * @param[in] counterHandle the counter handle + * @param[out] status Error status variable. 0 on success. * @return counter period */ int32_t HAL_GetDMASampleCounterPeriod(const HAL_DMASample* dmaSample, @@ -356,8 +386,9 @@ int32_t HAL_GetDMASampleCounterPeriod(const HAL_DMASample* dmaSample, /** * Returns the state of a digital source from the sample. * - * @param dmaSample the sample to read from - * @param dSourceHandle the digital source handle + * @param[in] dmaSample the sample to read from + * @param[in] dSourceHandle the digital source handle + * @param[out] status Error status variable. 0 on success. * @return digital source state */ HAL_Bool HAL_GetDMASampleDigitalSource(const HAL_DMASample* dmaSample, @@ -369,8 +400,9 @@ HAL_Bool HAL_GetDMASampleDigitalSource(const HAL_DMASample* dmaSample, * * This can be scaled with HAL_GetAnalogValueToVolts to match GetVoltage(). * - * @param dmaSample the sample to read from - * @param aInHandle the analog input handle + * @param[in] dmaSample the sample to read from + * @param[in] aInHandle the analog input handle + * @param[out] status Error status variable. 0 on success. * @return raw analog data */ int32_t HAL_GetDMASampleAnalogInputRaw(const HAL_DMASample* dmaSample, @@ -383,8 +415,9 @@ int32_t HAL_GetDMASampleAnalogInputRaw(const HAL_DMASample* dmaSample, * This can be scaled with HAL_GetAnalogValueToVolts to match * GetAveragedVoltage(). * - * @param dmaSample the sample to read from - * @param aInHandle the analog input handle + * @param[in] dmaSample the sample to read from + * @param[in] aInHandle the analog input handle + * @param[out] status Error status variable. 0 on success. * @return raw averaged analog data */ int32_t HAL_GetDMASampleAveragedAnalogInputRaw(const HAL_DMASample* dmaSample, @@ -394,10 +427,11 @@ int32_t HAL_GetDMASampleAveragedAnalogInputRaw(const HAL_DMASample* dmaSample, /** * Returns the analog accumulator data for an analog input from the sample. * - * @param dmaSample the sample to read from - * @param aInHandle the analog input handle - * @param count the accumulator count - * @param value the accumulator value + * @param[in] dmaSample the sample to read from + * @param[in] aInHandle the analog input handle + * @param[in] count the accumulator count + * @param[in] value the accumulator value + * @param[out] status Error status variable. 0 on success. */ void HAL_GetDMASampleAnalogAccumulator(const HAL_DMASample* dmaSample, HAL_AnalogInputHandle aInHandle, @@ -409,8 +443,9 @@ void HAL_GetDMASampleAnalogAccumulator(const HAL_DMASample* dmaSample, * * Use HAL_GetDutyCycleOutputScaleFactor to scale this to a percentage. * - * @param dmaSample the sample to read from - * @param dutyCycleHandle the duty cycle handle + * @param[in] dmaSample the sample to read from + * @param[in] dutyCycleHandle the duty cycle handle + * @param[out] status Error status variable. 0 on success. * @return raw duty cycle input data */ int32_t HAL_GetDMASampleDutyCycleOutputRaw(const HAL_DMASample* dmaSample, diff --git a/hal/src/main/native/include/hal/DriverStation.h b/hal/src/main/native/include/hal/DriverStation.h index c7df7c2351..fa03fcebb6 100644 --- a/hal/src/main/native/include/hal/DriverStation.h +++ b/hal/src/main/native/include/hal/DriverStation.h @@ -27,7 +27,7 @@ extern "C" { * @param isLVCode true for a LV error code, false for a standard error code * @param details the details of the error * @param location the file location of the errror - * @param callstack the callstack of the error + * @param callStack the callstack of the error * @param printMsg true to print the error message to stdout as well as to the * DS */ @@ -47,15 +47,15 @@ int32_t HAL_SendConsoleLine(const char* line); * The control work contains the robot state. * * @param controlWord the control word (out) - * @return the error code, or 0 for success + * @return the error code, or 0 for success */ int32_t HAL_GetControlWord(HAL_ControlWord* controlWord); /** * Gets the current alliance station ID. * - * @param status the error code, or 0 for success - * @return the alliance station ID + * @param[out] status the error code, or 0 for success + * @return the alliance station ID */ HAL_AllianceStationID HAL_GetAllianceStation(int32_t* status); @@ -64,7 +64,7 @@ HAL_AllianceStationID HAL_GetAllianceStation(int32_t* status); * * @param joystickNum the joystick number * @param axes the axes values (output) - * @return the error code, or 0 for success + * @return the error code, or 0 for success */ int32_t HAL_GetJoystickAxes(int32_t joystickNum, HAL_JoystickAxes* axes); @@ -73,7 +73,7 @@ int32_t HAL_GetJoystickAxes(int32_t joystickNum, HAL_JoystickAxes* axes); * * @param joystickNum the joystick number * @param povs the POV values (output) - * @return the error code, or 0 for success + * @return the error code, or 0 for success */ int32_t HAL_GetJoystickPOVs(int32_t joystickNum, HAL_JoystickPOVs* povs); @@ -82,7 +82,7 @@ int32_t HAL_GetJoystickPOVs(int32_t joystickNum, HAL_JoystickPOVs* povs); * * @param joystickNum the joystick number * @param buttons the button values (output) - * @return the error code, or 0 for success + * @return the error code, or 0 for success */ int32_t HAL_GetJoystickButtons(int32_t joystickNum, HAL_JoystickButtons* buttons); @@ -90,14 +90,15 @@ int32_t HAL_GetJoystickButtons(int32_t joystickNum, /** * Retrieves the Joystick Descriptor for particular slot. * - * @param desc [out] descriptor (data transfer object) to fill in. desc is - * filled in regardless of success. In other words, if descriptor is not - * available, desc is filled in with default values matching the init-values in - * Java and C++ Driverstation for when caller requests a too-large joystick - * index. - * + * @param joystickNum the joystick number + * @param[out] desc descriptor (data transfer object) to fill in. desc is + * filled in regardless of success. In other words, if + * descriptor is not available, desc is filled in with + * default values matching the init-values in Java and C++ + * Driver Station for when caller requests a too-large + * joystick index. * @return error code reported from Network Comm back-end. Zero is good, - * nonzero is bad. + * nonzero is bad. */ int32_t HAL_GetJoystickDescriptor(int32_t joystickNum, HAL_JoystickDescriptor* desc); @@ -106,7 +107,7 @@ int32_t HAL_GetJoystickDescriptor(int32_t joystickNum, * Gets is a specific joystick is considered to be an XBox controller. * * @param joystickNum the joystick number - * @return true if xbox, false otherwise + * @return true if xbox, false otherwise */ HAL_Bool HAL_GetJoystickIsXbox(int32_t joystickNum); @@ -117,7 +118,7 @@ HAL_Bool HAL_GetJoystickIsXbox(int32_t joystickNum); * the joystick uses. * * @param joystickNum the joystick number - * @return the enumerated joystick type + * @return the enumerated joystick type */ int32_t HAL_GetJoystickType(int32_t joystickNum); @@ -129,7 +130,7 @@ int32_t HAL_GetJoystickType(int32_t joystickNum); * Will be null terminated. * * @param joystickNum the joystick number - * @return the joystick name + * @return the joystick name */ char* HAL_GetJoystickName(int32_t joystickNum); @@ -148,7 +149,7 @@ void HAL_FreeJoystickName(char* name); * * @param joystickNum the joystick number * @param axis the axis number - * @return the enumerated axis type + * @return the enumerated axis type */ int32_t HAL_GetJoystickAxisType(int32_t joystickNum, int32_t axis); @@ -159,7 +160,7 @@ int32_t HAL_GetJoystickAxisType(int32_t joystickNum, int32_t axis); * @param outputs bitmask of outputs, 1 for on 0 for off * @param leftRumble the left rumble value (0-FFFF) * @param rightRumble the right rumble value (0-FFFF) - * @return the error code, or 0 for success + * @return the error code, or 0 for success */ int32_t HAL_SetJoystickOutputs(int32_t joystickNum, int64_t outputs, int32_t leftRumble, int32_t rightRumble); @@ -177,7 +178,7 @@ int32_t HAL_SetJoystickOutputs(int32_t joystickNum, int64_t outputs, * The Practice Match function of the DS approximates the behavior seen on * the field. * - * @param status the error code, or 0 for success + * @param[out] status the error code, or 0 for success * @return time remaining in current match period (auto or teleop) */ double HAL_GetMatchTime(int32_t* status); @@ -185,8 +186,8 @@ double HAL_GetMatchTime(int32_t* status); /** * Gets info about a specific match. * - * @param info the match info (output) - * @return the error code, or 0 for success + * @param[in] info the match info (output) + * @return the error code, or 0 for success */ int32_t HAL_GetMatchInfo(HAL_MatchInfo* info); @@ -217,8 +218,8 @@ void HAL_WaitForDSData(void); * forever. Otherwise, it will wait until either a new packet, or the timeout * time has passed. * - * @param timeout timeout in seconds - * @return true for new data, false for timeout + * @param[in] timeout timeout in seconds + * @return true for new data, false for timeout */ HAL_Bool HAL_WaitForDSDataTimeout(double timeout); diff --git a/hal/src/main/native/include/hal/DutyCycle.h b/hal/src/main/native/include/hal/DutyCycle.h index 5dddebb9db..05b654bc25 100644 --- a/hal/src/main/native/include/hal/DutyCycle.h +++ b/hal/src/main/native/include/hal/DutyCycle.h @@ -20,10 +20,12 @@ extern "C" { /** * Initialize a DutyCycle input. * - * @param digitalSourceHandle the digital source to use (either a - * HAL_DigitalHandle or a HAL_AnalogTriggerHandle) - * @param triggerType the analog trigger type of the source if it is - * an analog trigger + * @param[in] digitalSourceHandle the digital source to use (either a + * HAL_DigitalHandle or a + * HAL_AnalogTriggerHandle) + * @param[in] triggerType the analog trigger type of the source if it is + * an analog trigger + * @param[out] status Error status variable. 0 on success. * @return thre created duty cycle handle */ HAL_DutyCycleHandle HAL_InitializeDutyCycle(HAL_Handle digitalSourceHandle, @@ -49,7 +51,8 @@ void HAL_SetDutyCycleSimDevice(HAL_DutyCycleHandle handle, /** * Get the frequency of the duty cycle signal. * - * @param dutyCycleHandle the duty cycle handle + * @param[in] dutyCycleHandle the duty cycle handle + * @param[out] status Error status variable. 0 on success. * @return frequency in Hertz */ int32_t HAL_GetDutyCycleFrequency(HAL_DutyCycleHandle dutyCycleHandle, @@ -60,7 +63,8 @@ int32_t HAL_GetDutyCycleFrequency(HAL_DutyCycleHandle dutyCycleHandle, * *

0 means always low, 1 means always high. * - * @param dutyCycleHandle the duty cycle handle + * @param[in] dutyCycleHandle the duty cycle handle + * @param[out] status Error status variable. 0 on success. * @return output ratio between 0 and 1 */ double HAL_GetDutyCycleOutput(HAL_DutyCycleHandle dutyCycleHandle, @@ -72,7 +76,8 @@ double HAL_GetDutyCycleOutput(HAL_DutyCycleHandle dutyCycleHandle, *

0 means always low, an output equal to * GetOutputScaleFactor() means always high. * - * @param dutyCycleHandle the duty cycle handle + * @param[in] dutyCycleHandle the duty cycle handle + * @param[out] status Error status variable. 0 on success. * @return output ratio in raw units */ int32_t HAL_GetDutyCycleOutputRaw(HAL_DutyCycleHandle dutyCycleHandle, @@ -85,7 +90,8 @@ int32_t HAL_GetDutyCycleOutputRaw(HAL_DutyCycleHandle dutyCycleHandle, * down to 0. Divide the result of getOutputRaw by this in order to get the * percentage between 0 and 1. * - * @param dutyCycleHandle the duty cycle handle + * @param[in] dutyCycleHandle the duty cycle handle + * @param[out] status Error status variable. 0 on success. * @return the output scale factor */ int32_t HAL_GetDutyCycleOutputScaleFactor(HAL_DutyCycleHandle dutyCycleHandle, @@ -94,7 +100,8 @@ int32_t HAL_GetDutyCycleOutputScaleFactor(HAL_DutyCycleHandle dutyCycleHandle, /** * Get the FPGA index for the DutyCycle. * - * @param dutyCycleHandle the duty cycle handle + * @param[in] dutyCycleHandle the duty cycle handle + * @param[out] status Error status variable. 0 on success. * @return the FPGA index */ int32_t HAL_GetDutyCycleFPGAIndex(HAL_DutyCycleHandle dutyCycleHandle, diff --git a/hal/src/main/native/include/hal/Encoder.h b/hal/src/main/native/include/hal/Encoder.h index 8996257605..a6bf4afc5b 100644 --- a/hal/src/main/native/include/hal/Encoder.h +++ b/hal/src/main/native/include/hal/Encoder.h @@ -43,18 +43,19 @@ extern "C" { /** * Initializes an encoder. * - * @param digitalSourceHandleA the A source (either a HAL_DigitalHandle or a - * HAL_AnalogTriggerHandle) - * @param analogTriggerTypeA the analog trigger type of the A source if it is - * an analog trigger - * @param digitalSourceHandleB the B source (either a HAL_DigitalHandle or a - * HAL_AnalogTriggerHandle) - * @param analogTriggerTypeB the analog trigger type of the B source if it is - * an analog trigger - * @param reverseDirection true to reverse the counting direction from - * standard, otherwise false - * @param encodingType the encoding type - @return the created encoder handle + * @param[in] digitalSourceHandleA the A source (either a HAL_DigitalHandle or a + * HAL_AnalogTriggerHandle) + * @param[in] analogTriggerTypeA the analog trigger type of the A source if it + * is an analog trigger + * @param[in] digitalSourceHandleB the B source (either a HAL_DigitalHandle or a + * HAL_AnalogTriggerHandle) + * @param[in] analogTriggerTypeB the analog trigger type of the B source if it + * is an analog trigger + * @param[in] reverseDirection true to reverse the counting direction from + * standard, otherwise false + * @param[in] encodingType the encoding type + * @param[out] status Error status variable. 0 on success. + * @return the created encoder handle */ HAL_EncoderHandle HAL_InitializeEncoder( HAL_Handle digitalSourceHandleA, HAL_AnalogTriggerType analogTriggerTypeA, @@ -65,7 +66,8 @@ HAL_EncoderHandle HAL_InitializeEncoder( /** * Frees an encoder. * - * @param encoderHandle the encoder handle + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. */ void HAL_FreeEncoder(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -83,7 +85,8 @@ void HAL_SetEncoderSimDevice(HAL_EncoderHandle handle, * * This is scaled by the value passed duing initialization to encodingType. * - * @param encoderHandle the encoder handle + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. * @return the current scaled count */ int32_t HAL_GetEncoder(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -93,8 +96,9 @@ int32_t HAL_GetEncoder(HAL_EncoderHandle encoderHandle, int32_t* status); * * This is not scaled by any values. * - * @param encoderHandle the encoder handle - * @return the raw encoder count + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @return the raw encoder count */ int32_t HAL_GetEncoderRaw(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -103,8 +107,9 @@ int32_t HAL_GetEncoderRaw(HAL_EncoderHandle encoderHandle, int32_t* status); * * This is set by the value passed during initialization to encodingType. * - * @param encoderHandle the encoder handle - * @return the encoder scale value + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @return the encoder scale value */ int32_t HAL_GetEncoderEncodingScale(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -115,8 +120,8 @@ int32_t HAL_GetEncoderEncodingScale(HAL_EncoderHandle encoderHandle, * Read the value at this instant. It may still be running, so it reflects the * current value. Next time it is read, it might have a different value. * - * @param encoderHandle the encoder handle - * @return the current encoder value + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. */ void HAL_ResetEncoder(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -126,8 +131,9 @@ void HAL_ResetEncoder(HAL_EncoderHandle encoderHandle, int32_t* status); * Returns the time interval of the most recent count. This can be used for * velocity calculations to determine shaft speed. * - * @param encoderHandle the encoder handle - * @returns the period of the last two pulses in units of seconds + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @returns the period of the last two pulses in units of seconds */ double HAL_GetEncoderPeriod(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -138,9 +144,10 @@ double HAL_GetEncoderPeriod(HAL_EncoderHandle encoderHandle, int32_t* status); * used to determine the "stopped" state of the encoder using the * HAL_GetEncoderStopped method. * - * @param encoderHandle the encoder handle - * @param maxPeriod the maximum period where the counted device is - * considered moving in seconds + * @param[in] encoderHandle the encoder handle + * @param[in] maxPeriod the maximum period where the counted device is + * considered moving in seconds + * @param[out] status Error status variable. 0 on success. */ void HAL_SetEncoderMaxPeriod(HAL_EncoderHandle encoderHandle, double maxPeriod, int32_t* status); @@ -152,9 +159,10 @@ void HAL_SetEncoderMaxPeriod(HAL_EncoderHandle encoderHandle, double maxPeriod, * using the SetMaxPeriod method. If the clock exceeds the MaxPeriod, then the * device (and encoder) are assumed to be stopped and it returns true. * - * @param encoderHandle the encoder handle - * @return true if the most recent encoder period exceeds the - * MaxPeriod value set by SetMaxPeriod + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @return true if the most recent encoder period exceeds the MaxPeriod value + * set by SetMaxPeriod */ HAL_Bool HAL_GetEncoderStopped(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -162,8 +170,9 @@ HAL_Bool HAL_GetEncoderStopped(HAL_EncoderHandle encoderHandle, /** * Gets the last direction the encoder value changed. * - * @param encoderHandle the encoder handle - * @return the last direction the encoder value changed + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @return the last direction the encoder value changed */ HAL_Bool HAL_GetEncoderDirection(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -174,9 +183,10 @@ HAL_Bool HAL_GetEncoderDirection(HAL_EncoderHandle encoderHandle, * This is the encoder count scaled by the distance per pulse set for the * encoder. * - * @param encoderHandle the encoder handle - * @return the encoder distance (units are determined by the units - * passed to HAL_SetEncoderDistancePerPulse) + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @return the encoder distance (units are determined by the units + * passed to HAL_SetEncoderDistancePerPulse) */ double HAL_GetEncoderDistance(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -186,9 +196,10 @@ double HAL_GetEncoderDistance(HAL_EncoderHandle encoderHandle, int32_t* status); * This is the encoder period scaled by the distance per pulse set for the * encoder. * - * @param encoderHandle the encoder handle - * @return the encoder rate (units are determined by the units - * passed to HAL_SetEncoderDistancePerPulse, time value is seconds) + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @return the encoder rate (units are determined by the units passed to + * HAL_SetEncoderDistancePerPulse, time value is seconds) */ double HAL_GetEncoderRate(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -198,10 +209,12 @@ double HAL_GetEncoderRate(HAL_EncoderHandle encoderHandle, int32_t* status); * Units need to match what is set by HAL_SetEncoderDistancePerPulse, with time * as seconds. * - * @param encoderHandle the encoder handle - * @param minRate the minimum rate to be considered moving (units are - * determined by the units passed to HAL_SetEncoderDistancePerPulse, time value - * is seconds) + * @param[in] encoderHandle the encoder handle + * @param[in] minRate the minimum rate to be considered moving (units are + * determined by the units passed to + * HAL_SetEncoderDistancePerPulse, time value is + * seconds) + * @param[out] status Error status variable. 0 on success. */ void HAL_SetEncoderMinRate(HAL_EncoderHandle encoderHandle, double minRate, int32_t* status); @@ -210,9 +223,10 @@ void HAL_SetEncoderMinRate(HAL_EncoderHandle encoderHandle, double minRate, * Sets the distance traveled per encoder pulse. This is used as a scaling * factor for the rate and distance calls. * - * @param encoderHandle the encoder handle - * @param distancePerPulse the distance traveled per encoder pulse (units user - * defined) + * @param[in] encoderHandle the encoder handle + * @param[in] distancePerPulse the distance traveled per encoder pulse (units + * user defined) + * @param[out] status Error status variable. 0 on success. */ void HAL_SetEncoderDistancePerPulse(HAL_EncoderHandle encoderHandle, double distancePerPulse, int32_t* status); @@ -222,8 +236,9 @@ void HAL_SetEncoderDistancePerPulse(HAL_EncoderHandle encoderHandle, * * Note that this is not a toggle. It is an absolute set. * - * @param encoderHandle the encoder handle - * @param reverseDirection true to reverse the direction, false to not. + * @param[in] encoderHandle the encoder handle + * @param[in] reverseDirection true to reverse the direction, false to not. + * @param[out] status Error status variable. 0 on success. */ void HAL_SetEncoderReverseDirection(HAL_EncoderHandle encoderHandle, HAL_Bool reverseDirection, int32_t* status); @@ -231,8 +246,9 @@ void HAL_SetEncoderReverseDirection(HAL_EncoderHandle encoderHandle, /** * Sets the number of encoder samples to average when calculating encoder rate. * - * @param encoderHandle the encoder handle - * @param samplesToAverage the number of samples to average + * @param[in] encoderHandle the encoder handle + * @param[in] samplesToAverage the number of samples to average + * @param[out] status Error status variable. 0 on success. */ void HAL_SetEncoderSamplesToAverage(HAL_EncoderHandle encoderHandle, int32_t samplesToAverage, int32_t* status); @@ -240,8 +256,9 @@ void HAL_SetEncoderSamplesToAverage(HAL_EncoderHandle encoderHandle, /** * Gets the current samples to average value. * - * @param encoderHandle the encoder handle - * @return the current samples to average value + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @return the current samples to average value */ int32_t HAL_GetEncoderSamplesToAverage(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -252,12 +269,14 @@ int32_t HAL_GetEncoderSamplesToAverage(HAL_EncoderHandle encoderHandle, * The index pulse can be used to cause an encoder to reset based on an external * input. * - * @param encoderHandle the encoder handle - * @param digitalSourceHandle the index source handle (either a - * HAL_AnalogTriggerHandle or a HAL_DigitalHandle) - * @param analogTriggerType the analog trigger type if the source is an analog - * trigger - * @param type the index triggering type + * @param[in] encoderHandle the encoder handle + * @param[in] digitalSourceHandle the index source handle (either a + * HAL_AnalogTriggerHandle or a + * HAL_DigitalHandle) + * @param[in] analogTriggerType the analog trigger type if the source is an + * analog trigger + * @param[in] type the index triggering type + * @param[out] status Error status variable. 0 on success. */ void HAL_SetEncoderIndexSource(HAL_EncoderHandle encoderHandle, HAL_Handle digitalSourceHandle, @@ -267,8 +286,9 @@ void HAL_SetEncoderIndexSource(HAL_EncoderHandle encoderHandle, /** * Gets the FPGA index of the encoder. * - * @param encoderHandle the encoder handle - * @return the FPGA index of the encoder + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @return the FPGA index of the encoder */ int32_t HAL_GetEncoderFPGAIndex(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -278,8 +298,9 @@ int32_t HAL_GetEncoderFPGAIndex(HAL_EncoderHandle encoderHandle, * * This is used to perform the scaling from raw to type scaled values. * - * @param encoderHandle the encoder handle - * @return the scale value for the encoder + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @return the scale value for the encoder */ double HAL_GetEncoderDecodingScaleFactor(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -287,8 +308,9 @@ double HAL_GetEncoderDecodingScaleFactor(HAL_EncoderHandle encoderHandle, /** * Gets the user set distance per pulse of the encoder. * - * @param encoderHandle the encoder handle - * @return the set distance per pulse + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @return the set distance per pulse */ double HAL_GetEncoderDistancePerPulse(HAL_EncoderHandle encoderHandle, int32_t* status); @@ -296,8 +318,9 @@ double HAL_GetEncoderDistancePerPulse(HAL_EncoderHandle encoderHandle, /** * Gets the encoding type of the encoder. * - * @param encoderHandle the encoder handle - * @return the encoding type + * @param[in] encoderHandle the encoder handle + * @param[out] status Error status variable. 0 on success. + * @return the encoding type */ HAL_EncoderEncodingType HAL_GetEncoderEncodingType( HAL_EncoderHandle encoderHandle, int32_t* status); diff --git a/hal/src/main/native/include/hal/Extensions.h b/hal/src/main/native/include/hal/Extensions.h index 84708f743a..ad3f7335fd 100644 --- a/hal/src/main/native/include/hal/Extensions.h +++ b/hal/src/main/native/include/hal/Extensions.h @@ -32,7 +32,7 @@ extern "C" { * Expected to be called internally, not by users. * * @param library the library path - * @return the succes state of the initialization + * @return the succes state of the initialization */ int HAL_LoadOneExtension(const char* library); @@ -40,7 +40,7 @@ int HAL_LoadOneExtension(const char* library); * Loads any extra halsim libraries provided in the HALSIM_EXTENSIONS * environment variable. * - * @return the succes state of the initialization + * @return the succes state of the initialization */ int HAL_LoadExtensions(void); diff --git a/hal/src/main/native/include/hal/HALBase.h b/hal/src/main/native/include/hal/HALBase.h index fb937877fe..b31ec75013 100644 --- a/hal/src/main/native/include/hal/HALBase.h +++ b/hal/src/main/native/include/hal/HALBase.h @@ -28,10 +28,10 @@ extern "C" { * If passed HAL_USE_LAST_ERROR, the last error set on the thread will be * returned. * - * @param code the status code, set to the error status code if input is - * HAL_USE_LAST_ERROR - * @return the error message for the code. This does not need to be freed, - * but can be overwritten by another hal call on the same thread. + * @param[out] status the status code, set to the error status code if input is + * HAL_USE_LAST_ERROR + * @return the error message for the code. This does not need to be freed, + * but can be overwritten by another hal call on the same thread. */ const char* HAL_GetLastError(int32_t* status); @@ -39,7 +39,7 @@ const char* HAL_GetLastError(int32_t* status); * Gets the error message for a specific status code. * * @param code the status code - * @return the error message for the code. This does not need to be freed. + * @return the error message for the code. This does not need to be freed. */ const char* HAL_GetErrorMessage(int32_t code); @@ -48,6 +48,7 @@ const char* HAL_GetErrorMessage(int32_t code); * * For now, expect this to be competition year. * + * @param[out] status the error code, or 0 for success * @return FPGA Version number. */ int32_t HAL_GetFPGAVersion(int32_t* status); @@ -60,6 +61,7 @@ int32_t HAL_GetFPGAVersion(int32_t* status); * the next 8 bits are the Minor Revision. * The 12 least significant bits are the Build Number. * + * @param[out] status the error code, or 0 for success * @return FPGA Revision number. */ int64_t HAL_GetFPGARevision(int32_t* status); @@ -74,6 +76,7 @@ HAL_RuntimeType HAL_GetRuntimeType(void); /** * Gets the state of the "USER" button on the roboRIO. * + * @param[out] status the error code, or 0 for success * @return true if the button is currently pressed down */ HAL_Bool HAL_GetFPGAButton(int32_t* status); @@ -81,6 +84,7 @@ HAL_Bool HAL_GetFPGAButton(int32_t* status); /** * Gets if the system outputs are currently active * + * @param[out] status the error code, or 0 for success * @return true if the system outputs are active, false if disabled */ HAL_Bool HAL_GetSystemActive(int32_t* status); @@ -88,6 +92,7 @@ HAL_Bool HAL_GetSystemActive(int32_t* status); /** * Gets if the system is in a browned out state. * + * @param[out] status the error code, or 0 for success * @return true if the system is in a low voltage brown out, false otherwise */ HAL_Bool HAL_GetBrownedOut(int32_t* status); @@ -98,7 +103,7 @@ HAL_Bool HAL_GetBrownedOut(int32_t* status); * The created handle does not need to be freed. * * @param channel the channel number - * @return the created port + * @return the created port */ HAL_PortHandle HAL_GetPort(int32_t channel); @@ -112,13 +117,14 @@ HAL_PortHandle HAL_GetPort(int32_t channel); * * @param module the module number * @param channel the channel number - * @return the created port + * @return the created port */ HAL_PortHandle HAL_GetPortWithModule(int32_t module, int32_t channel); /** * Reads the microsecond-resolution timer on the FPGA. * + * @param[out] status the error code, or 0 for success * @return The current time in microseconds according to the FPGA (since FPGA * reset). */ @@ -133,10 +139,12 @@ uint64_t HAL_GetFPGATime(int32_t* status); * bottom 32 bits of the timestamp and expanding it, you will be off by * multiples of 1<<32 microseconds. * + * @param[in] unexpandedLower 32 bit FPGA time + * @param[out] status the error code, or 0 for success * @return The current time in microseconds according to the FPGA (since FPGA - * reset) as a 64 bit number. + * reset) as a 64 bit number. */ -uint64_t HAL_ExpandFPGATime(uint32_t unexpanded_lower, int32_t* status); +uint64_t HAL_ExpandFPGATime(uint32_t unexpandedLower, int32_t* status); /** * Call this to start up HAL. This is required for robot programs. @@ -160,7 +168,7 @@ uint64_t HAL_ExpandFPGATime(uint32_t unexpanded_lower, int32_t* status); * * @param timeout the initialization timeout (ms) * @param mode the initialization mode (see remarks) - * @return true if initialization was successful, otherwise false. + * @return true if initialization was successful, otherwise false. */ HAL_Bool HAL_Initialize(int32_t timeout, int32_t mode); diff --git a/hal/src/main/native/include/hal/I2C.h b/hal/src/main/native/include/hal/I2C.h index 31dd16edd2..4e5c007155 100644 --- a/hal/src/main/native/include/hal/I2C.h +++ b/hal/src/main/native/include/hal/I2C.h @@ -24,7 +24,8 @@ extern "C" { * Opens the port if necessary and saves the handle. * If opening the MXP port, also sets up the channel functions appropriately. * - * @param port The port to open, 0 for the on-board, 1 for the MXP. + * @param[in] port The port to open, 0 for the on-board, 1 for the MXP. + * @param[out] status Error status variable. 0 on success. */ void HAL_InitializeI2C(HAL_I2CPort port, int32_t* status); @@ -35,6 +36,8 @@ void HAL_InitializeI2C(HAL_I2CPort port, int32_t* status); * over each transaction. * * @param port The I2C port, 0 for the on-board, 1 for the MXP. + * @param deviceAddress The address of the register on the device to be + * read/written. * @param dataToSend Buffer of data to send as part of the transaction. * @param sendSize Number of bytes to send as part of the transaction. * @param dataReceived Buffer to read data into. @@ -52,9 +55,10 @@ int32_t HAL_TransactionI2C(HAL_I2CPort port, int32_t deviceAddress, * transaction is complete. * * @param port The I2C port, 0 for the on-board, 1 for the MXP. - * @param registerAddress The address of the register on the device to be - * written. - * @param data The byte to write to the register on the device. + * @param deviceAddress The address of the register on the device to be + * written. + * @param dataToSend The byte to write to the register on the device. + * @param sendSize Number of bytes to send. * @return >= 0 on success or -1 on transfer abort. */ int32_t HAL_WriteI2C(HAL_I2CPort port, int32_t deviceAddress, @@ -68,7 +72,7 @@ int32_t HAL_WriteI2C(HAL_I2CPort port, int32_t deviceAddress, * you to read consecutive registers on a device in a single transaction. * * @param port The I2C port, 0 for the on-board, 1 for the MXP. - * @param registerAddress The register to read first in the transaction. + * @param deviceAddress The register to read first in the transaction. * @param count The number of bytes to read in the transaction. * @param buffer A pointer to the array of bytes to store the data read from the * device. diff --git a/hal/src/main/native/include/hal/Interrupts.h b/hal/src/main/native/include/hal/Interrupts.h index 4df327b829..def800ce99 100644 --- a/hal/src/main/native/include/hal/Interrupts.h +++ b/hal/src/main/native/include/hal/Interrupts.h @@ -22,8 +22,8 @@ extern "C" { /** * Initializes an interrupt. * - * @param watcher true for synchronous interrupts, false for asynchronous - * @return the created interrupt handle + * @param[out] status Error status variable. 0 on success. + * @return the created interrupt handle */ HAL_InterruptHandle HAL_InitializeInterrupts(int32_t* status); @@ -37,11 +37,12 @@ void HAL_CleanInterrupts(HAL_InterruptHandle interruptHandle); /** * In synchronous mode, waits for the defined interrupt to occur. * - * @param interruptHandle the interrupt handle - * @param timeout timeout in seconds - * @param ignorePrevious if true, ignore interrupts that happened before - * waitForInterrupt was called - * @return the mask of interrupts that fired + * @param[in] interruptHandle the interrupt handle + * @param[in] timeout timeout in seconds + * @param[in] ignorePrevious if true, ignore interrupts that happened before + * waitForInterrupt was called + * @param[out] status Error status variable. 0 on success. + * @return the mask of interrupts that fired */ int64_t HAL_WaitForInterrupt(HAL_InterruptHandle interruptHandle, double timeout, HAL_Bool ignorePrevious, @@ -54,8 +55,9 @@ int64_t HAL_WaitForInterrupt(HAL_InterruptHandle interruptHandle, * bottom 32 bits of the timestamp. If your robot has been running for over 1 * hour, you will need to fill in the upper 32 bits yourself. * - * @param interruptHandle the interrupt handle - * @return timestamp in microseconds since FPGA Initialization + * @param[in] interruptHandle the interrupt handle + * @param[out] status Error status variable. 0 on success. + * @return timestamp in microseconds since FPGA Initialization */ int64_t HAL_ReadInterruptRisingTimestamp(HAL_InterruptHandle interruptHandle, int32_t* status); @@ -67,8 +69,9 @@ int64_t HAL_ReadInterruptRisingTimestamp(HAL_InterruptHandle interruptHandle, * bottom 32 bits of the timestamp. If your robot has been running for over 1 * hour, you will need to fill in the upper 32 bits yourself. * - * @param interruptHandle the interrupt handle - * @return timestamp in microseconds since FPGA Initialization + * @param[in] interruptHandle the interrupt handle + * @param[out] status Error status variable. 0 on success. + * @return timestamp in microseconds since FPGA Initialization */ int64_t HAL_ReadInterruptFallingTimestamp(HAL_InterruptHandle interruptHandle, int32_t* status); @@ -76,10 +79,13 @@ int64_t HAL_ReadInterruptFallingTimestamp(HAL_InterruptHandle interruptHandle, /** * Requests interrupts on a specific digital source. * - * @param interruptHandle the interrupt handle - * @param digitalSourceHandle the digital source handle (either a - * HAL_AnalogTriggerHandle or a HAL_DigitalHandle) - * @param analogTriggerType the trigger type if the source is an AnalogTrigger + * @param[in] interruptHandle the interrupt handle + * @param[in] digitalSourceHandle the digital source handle (either a + * HAL_AnalogTriggerHandle or a + * HAL_DigitalHandle) + * @param[in] analogTriggerType the trigger type if the source is an + * AnalogTrigger + * @param[out] status Error status variable. 0 on success. */ void HAL_RequestInterrupts(HAL_InterruptHandle interruptHandle, HAL_Handle digitalSourceHandle, @@ -91,9 +97,10 @@ void HAL_RequestInterrupts(HAL_InterruptHandle interruptHandle, * * Note that both edges triggered is a valid configuration. * - * @param interruptHandle the interrupt handle - * @param risingEdge true for triggering on rising edge - * @param fallingEdge true for triggering on falling edge + * @param[in] interruptHandle the interrupt handle + * @param[in] risingEdge true for triggering on rising edge + * @param[in] fallingEdge true for triggering on falling edge + * @param[out] status Error status variable. 0 on success. */ void HAL_SetInterruptUpSourceEdge(HAL_InterruptHandle interruptHandle, HAL_Bool risingEdge, HAL_Bool fallingEdge, @@ -104,7 +111,8 @@ void HAL_SetInterruptUpSourceEdge(HAL_InterruptHandle interruptHandle, * * This will release both rising and falling waiters. * - * @param interruptHandle the interrupt handle to release + * @param[in] interruptHandle the interrupt handle to release + * @param[out] status Error status variable. 0 on success. */ void HAL_ReleaseWaitingInterrupt(HAL_InterruptHandle interruptHandle, int32_t* status); diff --git a/hal/src/main/native/include/hal/Notifier.h b/hal/src/main/native/include/hal/Notifier.h index f835b884cf..96452f4cc8 100644 --- a/hal/src/main/native/include/hal/Notifier.h +++ b/hal/src/main/native/include/hal/Notifier.h @@ -26,6 +26,7 @@ extern "C" { * A notifier is an FPGA controller timer that triggers at requested intervals * based on the FPGA time. This can be used to make precise control loops. * + * @param[out] status Error status variable. 0 on success. * @return the created notifier */ HAL_NotifierHandle HAL_InitializeNotifier(int32_t* status); @@ -38,13 +39,13 @@ HAL_NotifierHandle HAL_InitializeNotifier(int32_t* status); * Giving the HAL notifier thread real-time priority helps ensure the user's * real-time Notifiers, if any, are notified to run in a timely manner. * - * @param realTime Set to true to set a real-time priority, false for standard - * priority. - * @param priority Priority to set the thread to. For real-time, this is 1-99 - * with 99 being highest. For non-real-time, this is forced to - * 0. See "man 7 sched" for more details. - * @param status Error status variable. 0 on success. - * @return True on success. + * @param[in] realTime Set to true to set a real-time priority, false for + * standard priority. + * @param[in] priority Priority to set the thread to. For real-time, this is + * 1-99 with 99 being highest. For non-real-time, this is + * forced to 0. See "man 7 sched" for more details. + * @param[out] status Error status variable. 0 on success. + * @return True on success. */ HAL_Bool HAL_SetNotifierThreadPriority(HAL_Bool realTime, int32_t priority, int32_t* status); @@ -52,8 +53,9 @@ HAL_Bool HAL_SetNotifierThreadPriority(HAL_Bool realTime, int32_t priority, /** * Sets the name of a notifier. * - * @param notifierHandle the notifier handle - * @param name name + * @param[in] notifierHandle the notifier handle + * @param[in] name name + * @param[out] status Error status variable. 0 on success. */ void HAL_SetNotifierName(HAL_NotifierHandle notifierHandle, const char* name, int32_t* status); @@ -63,7 +65,8 @@ void HAL_SetNotifierName(HAL_NotifierHandle notifierHandle, const char* name, * * This will cause any call into HAL_WaitForNotifierAlarm to return. * - * @param notifierHandle the notifier handle + * @param[in] notifierHandle the notifier handle + * @param[out] status Error status variable. 0 on success. */ void HAL_StopNotifier(HAL_NotifierHandle notifierHandle, int32_t* status); @@ -72,7 +75,8 @@ void HAL_StopNotifier(HAL_NotifierHandle notifierHandle, int32_t* status); * * Note this also stops a notifier if it is already running. * - * @param notifierHandle the notifier handle + * @param[in] notifierHandle the notifier handle + * @param[out] status Error status variable. 0 on success. */ void HAL_CleanNotifier(HAL_NotifierHandle notifierHandle, int32_t* status); @@ -81,8 +85,9 @@ void HAL_CleanNotifier(HAL_NotifierHandle notifierHandle, int32_t* status); * * Note that this time is an absolute time relative to HAL_GetFPGATime() * - * @param notifierHandle the notifier handle - * @param triggerTime the updated trigger time + * @param[in] notifierHandle the notifier handle + * @param[in] triggerTime the updated trigger time + * @param[out] status Error status variable. 0 on success. */ void HAL_UpdateNotifierAlarm(HAL_NotifierHandle notifierHandle, uint64_t triggerTime, int32_t* status); @@ -92,7 +97,8 @@ void HAL_UpdateNotifierAlarm(HAL_NotifierHandle notifierHandle, * * This does not cause HAL_WaitForNotifierAlarm to return. * - * @param notifierHandle the notifier handle + * @param[in] notifierHandle the notifier handle + * @param[out] status Error status variable. 0 on success. */ void HAL_CancelNotifierAlarm(HAL_NotifierHandle notifierHandle, int32_t* status); @@ -105,8 +111,9 @@ void HAL_CancelNotifierAlarm(HAL_NotifierHandle notifierHandle, * loops using this function should exit. Failing to do so can lead to * use-after-frees. * - * @param notifierHandle the notifier handle - * @return the FPGA time the notifier returned + * @param[in] notifierHandle the notifier handle + * @param[out] status Error status variable. 0 on success. + * @return the FPGA time the notifier returned */ WPI_NODISCARD uint64_t HAL_WaitForNotifierAlarm(HAL_NotifierHandle notifierHandle, diff --git a/hal/src/main/native/include/hal/PWM.h b/hal/src/main/native/include/hal/PWM.h index 04bfc4f73e..7fd125e801 100644 --- a/hal/src/main/native/include/hal/PWM.h +++ b/hal/src/main/native/include/hal/PWM.h @@ -21,10 +21,11 @@ extern "C" { /** * Initializes a PWM port. * - * @param portHandle the port to initialize - * @param allocationLocation the location where the allocation is occuring - * (can be null) - * @return the created pwm handle + * @param[in] portHandle the port to initialize + * @param[in] allocationLocation the location where the allocation is occuring + * (can be null) + * @param[out] status Error status variable. 0 on success. + * @return the created pwm handle */ HAL_DigitalHandle HAL_InitializePWMPort(HAL_PortHandle portHandle, const char* allocationLocation, @@ -33,7 +34,8 @@ HAL_DigitalHandle HAL_InitializePWMPort(HAL_PortHandle portHandle, /** * Frees a PWM port. * - * @param pwmPortHandle the pwm handle + * @param[in] pwmPortHandle the pwm handle + * @param[out] status Error status variable. 0 on success. */ void HAL_FreePWMPort(HAL_DigitalHandle pwmPortHandle, int32_t* status); @@ -41,7 +43,7 @@ void HAL_FreePWMPort(HAL_DigitalHandle pwmPortHandle, int32_t* status); * Checks if a pwm channel is valid. * * @param channel the channel to check - * @return true if the channel is valid, otherwise false + * @return true if the channel is valid, otherwise false */ HAL_Bool HAL_CheckPWMChannel(int32_t channel); @@ -50,12 +52,13 @@ HAL_Bool HAL_CheckPWMChannel(int32_t channel); * * All values are in milliseconds. * - * @param pwmPortHandle the PWM handle - * @param maxPwm the maximum PWM value - * @param deadbandMaxPwm the high range of the center deadband - * @param centerPwm the center PWM value - * @param deadbandMinPwm the low range of the center deadband - * @param minPwm the minimum PWM value + * @param[in] pwmPortHandle the PWM handle + * @param[in] maxPwm the maximum PWM value + * @param[in] deadbandMaxPwm the high range of the center deadband + * @param[in] centerPwm the center PWM value + * @param[in] deadbandMinPwm the low range of the center deadband + * @param[in] minPwm the minimum PWM value + * @param[out] status Error status variable. 0 on success. */ void HAL_SetPWMConfig(HAL_DigitalHandle pwmPortHandle, double maxPwm, double deadbandMaxPwm, double centerPwm, @@ -69,12 +72,13 @@ void HAL_SetPWMConfig(HAL_DigitalHandle pwmPortHandle, double maxPwm, * * Values are in raw FPGA units. * - * @param pwmPortHandle the PWM handle - * @param maxPwm the maximum PWM value - * @param deadbandMaxPwm the high range of the center deadband - * @param centerPwm the center PWM value - * @param deadbandMinPwm the low range of the center deadband - * @param minPwm the minimum PWM value + * @param[in] pwmPortHandle the PWM handle + * @param[in] maxPwm the maximum PWM value + * @param[in] deadbandMaxPwm the high range of the center deadband + * @param[in] centerPwm the center PWM value + * @param[in] deadbandMinPwm the low range of the center deadband + * @param[in] minPwm the minimum PWM value + * @param[out] status Error status variable. 0 on success. */ void HAL_SetPWMConfigRaw(HAL_DigitalHandle pwmPortHandle, int32_t maxPwm, int32_t deadbandMaxPwm, int32_t centerPwm, @@ -87,12 +91,13 @@ void HAL_SetPWMConfigRaw(HAL_DigitalHandle pwmPortHandle, int32_t maxPwm, * Values are in raw FPGA units. These units have the potential to change for * any FPGA release. * - * @param pwmPortHandle the PWM handle - * @param maxPwm the maximum PWM value - * @param deadbandMaxPwm the high range of the center deadband - * @param centerPwm the center PWM value - * @param deadbandMinPwm the low range of the center deadband - * @param minPwm the minimum PWM value + * @param[in] pwmPortHandle the PWM handle + * @param[in] maxPwm the maximum PWM value + * @param[in] deadbandMaxPwm the high range of the center deadband + * @param[in] centerPwm the center PWM value + * @param[in] deadbandMinPwm the low range of the center deadband + * @param[in] minPwm the minimum PWM value + * @param[out] status Error status variable. 0 on success. */ void HAL_GetPWMConfigRaw(HAL_DigitalHandle pwmPortHandle, int32_t* maxPwm, int32_t* deadbandMaxPwm, int32_t* centerPwm, @@ -103,8 +108,9 @@ void HAL_GetPWMConfigRaw(HAL_DigitalHandle pwmPortHandle, int32_t* maxPwm, * Sets if the FPGA should output the center value if the input value is within * the deadband. * - * @param pwmPortHandle the PWM handle - * @param eliminateDeadband true to eliminate deadband, otherwise false + * @param[in] pwmPortHandle the PWM handle + * @param[in] eliminateDeadband true to eliminate deadband, otherwise false + * @param[out] status Error status variable. 0 on success. */ void HAL_SetPWMEliminateDeadband(HAL_DigitalHandle pwmPortHandle, HAL_Bool eliminateDeadband, int32_t* status); @@ -112,8 +118,9 @@ void HAL_SetPWMEliminateDeadband(HAL_DigitalHandle pwmPortHandle, /** * Gets the current eliminate deadband value. * - * @param pwmPortHandle the PWM handle - * @return true if set, otherwise false + * @param[in] pwmPortHandle the PWM handle + * @param[out] status Error status variable. 0 on success. + * @return true if set, otherwise false */ HAL_Bool HAL_GetPWMEliminateDeadband(HAL_DigitalHandle pwmPortHandle, int32_t* status); @@ -124,8 +131,9 @@ HAL_Bool HAL_GetPWMEliminateDeadband(HAL_DigitalHandle pwmPortHandle, * The values are in raw FPGA units, and have the potential to change with any * FPGA release. * - * @param pwmPortHandle the PWM handle - * @param value the PWM value to set + * @param[in] pwmPortHandle the PWM handle + * @param[in] value the PWM value to set + * @param[out] status Error status variable. 0 on success. */ void HAL_SetPWMRaw(HAL_DigitalHandle pwmPortHandle, int32_t value, int32_t* status); @@ -136,8 +144,9 @@ void HAL_SetPWMRaw(HAL_DigitalHandle pwmPortHandle, int32_t value, * The values range from -1 to 1 and the period is controlled by the PWM Period * and MinHigh registers. * - * @param pwmPortHandle the PWM handle - * @param value the scaled PWM value to set + * @param[in] pwmPortHandle the PWM handle + * @param[in] speed the scaled PWM value to set + * @param[out] status Error status variable. 0 on success. */ void HAL_SetPWMSpeed(HAL_DigitalHandle pwmPortHandle, double speed, int32_t* status); @@ -148,8 +157,9 @@ void HAL_SetPWMSpeed(HAL_DigitalHandle pwmPortHandle, double speed, * The values range from 0 to 1 and the period is controlled by the PWM Period * and MinHigh registers. * - * @param pwmPortHandle the PWM handle - * @param value the positional PWM value to set + * @param[in] pwmPortHandle the PWM handle + * @param[in] position the positional PWM value to set + * @param[out] status Error status variable. 0 on success. */ void HAL_SetPWMPosition(HAL_DigitalHandle pwmPortHandle, double position, int32_t* status); @@ -161,7 +171,8 @@ void HAL_SetPWMPosition(HAL_DigitalHandle pwmPortHandle, double position, * from just setting a 0 speed, as this will actively stop all signaling on the * channel. * - * @param pwmPortHandle the PWM handle. + * @param[in] pwmPortHandle the PWM handle. + * @param[out] status Error status variable. 0 on success. */ void HAL_SetPWMDisabled(HAL_DigitalHandle pwmPortHandle, int32_t* status); @@ -171,8 +182,9 @@ void HAL_SetPWMDisabled(HAL_DigitalHandle pwmPortHandle, int32_t* status); * The values are in raw FPGA units, and have the potential to change with any * FPGA release. * - * @param pwmPortHandle the PWM handle - * @return the current raw PWM value + * @param[in] pwmPortHandle the PWM handle + * @param[out] status Error status variable. 0 on success. + * @return the current raw PWM value */ int32_t HAL_GetPWMRaw(HAL_DigitalHandle pwmPortHandle, int32_t* status); @@ -181,8 +193,9 @@ int32_t HAL_GetPWMRaw(HAL_DigitalHandle pwmPortHandle, int32_t* status); * * The values range from -1 to 1. * - * @param pwmPortHandle the PWM handle - * @return the current speed PWM value + * @param[in] pwmPortHandle the PWM handle + * @param[out] status Error status variable. 0 on success. + * @return the current speed PWM value */ double HAL_GetPWMSpeed(HAL_DigitalHandle pwmPortHandle, int32_t* status); @@ -191,23 +204,26 @@ double HAL_GetPWMSpeed(HAL_DigitalHandle pwmPortHandle, int32_t* status); * * The values range from 0 to 1. * - * @param pwmPortHandle the PWM handle - * @return the current positional PWM value + * @param[in] pwmPortHandle the PWM handle + * @param[out] status Error status variable. 0 on success. + * @return the current positional PWM value */ double HAL_GetPWMPosition(HAL_DigitalHandle pwmPortHandle, int32_t* status); /** * Forces a PWM signal to go to 0 temporarily. * - * @param pwmPortHandle the PWM handle. + * @param[in] pwmPortHandle the PWM handle. + * @param[out] status Error status variable. 0 on success. */ void HAL_LatchPWMZero(HAL_DigitalHandle pwmPortHandle, int32_t* status); /** * Sets how how often the PWM signal is squelched, thus scaling the period. * - * @param pwmPortHandle the PWM handle. - * @param squelchMask the 2-bit mask of outputs to squelch + * @param[in] pwmPortHandle the PWM handle. + * @param[in] squelchMask the 2-bit mask of outputs to squelch + * @param[out] status Error status variable. 0 on success. */ void HAL_SetPWMPeriodScale(HAL_DigitalHandle pwmPortHandle, int32_t squelchMask, int32_t* status); @@ -215,6 +231,7 @@ void HAL_SetPWMPeriodScale(HAL_DigitalHandle pwmPortHandle, int32_t squelchMask, /** * Gets the loop timing of the PWM system. * + * @param[out] status Error status variable. 0 on success. * @return the loop time */ int32_t HAL_GetPWMLoopTiming(int32_t* status); @@ -224,6 +241,7 @@ int32_t HAL_GetPWMLoopTiming(int32_t* status); * * This time is relative to the FPGA time. * + * @param[out] status Error status variable. 0 on success. * @return the pwm cycle start time */ uint64_t HAL_GetPWMCycleStartTime(int32_t* status); diff --git a/hal/src/main/native/include/hal/Power.h b/hal/src/main/native/include/hal/Power.h index afb31863a5..2bd983a359 100644 --- a/hal/src/main/native/include/hal/Power.h +++ b/hal/src/main/native/include/hal/Power.h @@ -21,6 +21,7 @@ extern "C" { /** * Gets the roboRIO input voltage. * + * @param[out] status the error code, or 0 for success * @return the input voltage (volts) */ double HAL_GetVinVoltage(int32_t* status); @@ -28,6 +29,7 @@ double HAL_GetVinVoltage(int32_t* status); /** * Gets the roboRIO input current. * + * @param[out] status the error code, or 0 for success * @return the input current (amps) */ double HAL_GetVinCurrent(int32_t* status); @@ -35,6 +37,7 @@ double HAL_GetVinCurrent(int32_t* status); /** * Gets the 6V rail voltage. * + * @param[out] status the error code, or 0 for success * @return the 6V rail voltage (volts) */ double HAL_GetUserVoltage6V(int32_t* status); @@ -42,6 +45,7 @@ double HAL_GetUserVoltage6V(int32_t* status); /** * Gets the 6V rail current. * + * @param[out] status the error code, or 0 for success * @return the 6V rail current (amps) */ double HAL_GetUserCurrent6V(int32_t* status); @@ -49,6 +53,7 @@ double HAL_GetUserCurrent6V(int32_t* status); /** * Gets the active state of the 6V rail. * + * @param[out] status the error code, or 0 for success * @return true if the rail is active, otherwise false */ HAL_Bool HAL_GetUserActive6V(int32_t* status); @@ -56,6 +61,7 @@ HAL_Bool HAL_GetUserActive6V(int32_t* status); /** * Gets the fault count for the 6V rail. * + * @param[out] status the error code, or 0 for success * @return the number of 6V fault counts */ int32_t HAL_GetUserCurrentFaults6V(int32_t* status); @@ -63,6 +69,7 @@ int32_t HAL_GetUserCurrentFaults6V(int32_t* status); /** * Gets the 5V rail voltage. * + * @param[out] status the error code, or 0 for success * @return the 5V rail voltage (volts) */ double HAL_GetUserVoltage5V(int32_t* status); @@ -70,6 +77,7 @@ double HAL_GetUserVoltage5V(int32_t* status); /** * Gets the 5V rail current. * + * @param[out] status the error code, or 0 for success * @return the 5V rail current (amps) */ double HAL_GetUserCurrent5V(int32_t* status); @@ -77,6 +85,7 @@ double HAL_GetUserCurrent5V(int32_t* status); /** * Gets the active state of the 5V rail. * + * @param[out] status the error code, or 0 for success * @return true if the rail is active, otherwise false */ HAL_Bool HAL_GetUserActive5V(int32_t* status); @@ -84,6 +93,7 @@ HAL_Bool HAL_GetUserActive5V(int32_t* status); /** * Gets the fault count for the 5V rail. * + * @param[out] status the error code, or 0 for success * @return the number of 5V fault counts */ int32_t HAL_GetUserCurrentFaults5V(int32_t* status); @@ -91,6 +101,7 @@ int32_t HAL_GetUserCurrentFaults5V(int32_t* status); /** * Gets the 3V3 rail voltage. * + * @param[out] status the error code, or 0 for success * @return the 3V3 rail voltage (volts) */ double HAL_GetUserVoltage3V3(int32_t* status); @@ -98,6 +109,7 @@ double HAL_GetUserVoltage3V3(int32_t* status); /** * Gets the 3V3 rail current. * + * @param[out] status the error code, or 0 for success * @return the 3V3 rail current (amps) */ double HAL_GetUserCurrent3V3(int32_t* status); @@ -105,6 +117,7 @@ double HAL_GetUserCurrent3V3(int32_t* status); /** * Gets the active state of the 3V3 rail. * + * @param[out] status the error code, or 0 for success * @return true if the rail is active, otherwise false */ HAL_Bool HAL_GetUserActive3V3(int32_t* status); @@ -112,6 +125,7 @@ HAL_Bool HAL_GetUserActive3V3(int32_t* status); /** * Gets the fault count for the 3V3 rail. * + * @param[out] status the error code, or 0 for success * @return the number of 3V3 fault counts */ int32_t HAL_GetUserCurrentFaults3V3(int32_t* status); @@ -119,6 +133,7 @@ int32_t HAL_GetUserCurrentFaults3V3(int32_t* status); /** * Get the current brownout voltage setting. * + * @param[out] status the error code, or 0 for success * @return The brownout voltage */ double HAL_GetBrownoutVoltage(int32_t* status); @@ -129,7 +144,8 @@ double HAL_GetBrownoutVoltage(int32_t* status); * Note that this only does anything on the roboRIO 2. * On the roboRIO it is a no-op. * - * @param voltage The brownout voltage + * @param[in] voltage The brownout voltage + * @param[out] status the error code, or 0 for success */ void HAL_SetBrownoutVoltage(double voltage, int32_t* status); diff --git a/hal/src/main/native/include/hal/PowerDistribution.h b/hal/src/main/native/include/hal/PowerDistribution.h index 99032af412..fabb8b7389 100644 --- a/hal/src/main/native/include/hal/PowerDistribution.h +++ b/hal/src/main/native/include/hal/PowerDistribution.h @@ -35,8 +35,10 @@ extern "C" { /** * Initializes a Power Distribution Panel. * - * @param module the module number to initialize - * @param type the type of module to intialize + * @param[in] moduleNumber the module number to initialize + * @param[in] type the type of module to intialize + * @param[in] allocationLocation the location where the allocation is occuring + * @param[out] status Error status variable. 0 on success. * @return the created PowerDistribution */ HAL_PowerDistributionHandle HAL_InitializePowerDistribution( @@ -46,7 +48,8 @@ HAL_PowerDistributionHandle HAL_InitializePowerDistribution( /** * Gets the module number for a specific handle. * - * @param handle the module handle + * @param[in] handle the module handle + * @param[out] status Error status variable. 0 on success. * @return the module number */ int32_t HAL_GetPowerDistributionModuleNumber(HAL_PowerDistributionHandle handle, @@ -62,9 +65,9 @@ void HAL_CleanPowerDistribution(HAL_PowerDistributionHandle handle); /** * Checks if a PowerDistribution channel is valid. * - * @param handle the module handle + * @param handle the module handle * @param channel the channel to check - * @return true if the channel is valid, otherwise false + * @return true if the channel is valid, otherwise false */ HAL_Bool HAL_CheckPowerDistributionChannel(HAL_PowerDistributionHandle handle, int32_t channel); @@ -72,8 +75,9 @@ HAL_Bool HAL_CheckPowerDistributionChannel(HAL_PowerDistributionHandle handle, /** * Checks if a PowerDistribution module is valid. * - * @param channel the module to check - * @return true if the module is valid, otherwise false + * @param module the module to check + * @param type the type of module + * @return true if the module is valid, otherwise false */ HAL_Bool HAL_CheckPowerDistributionModule(int32_t module, HAL_PowerDistributionType type); @@ -81,6 +85,8 @@ HAL_Bool HAL_CheckPowerDistributionModule(int32_t module, /** * Gets the type of PowerDistribution module. * + * @param[in] handle the module handle + * @param[out] status Error status variable. 0 on success. * @return the type of module */ HAL_PowerDistributionType HAL_GetPowerDistributionType( @@ -89,7 +95,8 @@ HAL_PowerDistributionType HAL_GetPowerDistributionType( /** * Gets the number of channels for this handle. * - * @param handle the handle + * @param[in] handle the handle + * @param[out] status Error status variable. 0 on success. * @return number of channels */ int32_t HAL_GetPowerDistributionNumChannels(HAL_PowerDistributionHandle handle, @@ -98,8 +105,9 @@ int32_t HAL_GetPowerDistributionNumChannels(HAL_PowerDistributionHandle handle, /** * Gets the temperature of the PowerDistribution. * - * @param handle the module handle - * @return the module temperature (celsius) + * @param[in] handle the module handle + * @param[out] status Error status variable. 0 on success. + * @return the module temperature (celsius) */ double HAL_GetPowerDistributionTemperature(HAL_PowerDistributionHandle handle, int32_t* status); @@ -107,8 +115,9 @@ double HAL_GetPowerDistributionTemperature(HAL_PowerDistributionHandle handle, /** * Gets the PowerDistribution input voltage. * - * @param handle the module handle - * @return the input voltage (volts) + * @param[in] handle the module handle + * @param[out] status Error status variable. 0 on success. + * @return the input voltage (volts) */ double HAL_GetPowerDistributionVoltage(HAL_PowerDistributionHandle handle, int32_t* status); @@ -116,9 +125,10 @@ double HAL_GetPowerDistributionVoltage(HAL_PowerDistributionHandle handle, /** * Gets the current of a specific PowerDistribution channel. * - * @param module the module - * @param channel the channel - * @return the channel current (amps) + * @param[in] handle the module handle + * @param[in] channel the channel + * @param[out] status Error status variable. 0 on success. + * @return the channel current (amps) */ double HAL_GetPowerDistributionChannelCurrent( HAL_PowerDistributionHandle handle, int32_t channel, int32_t* status); @@ -128,9 +138,10 @@ double HAL_GetPowerDistributionChannelCurrent( * * The array must be large enough to hold all channels. * - * @param handle the module handle - * @param currents the currents (output) - * @param currentsLength the length of the currents array + * @param[in] handle the module handle + * @param[out] currents the currents + * @param[in] currentsLength the length of the currents array + * @param[out] status Error status variable. 0 on success. */ void HAL_GetPowerDistributionAllChannelCurrents( HAL_PowerDistributionHandle handle, double* currents, @@ -139,8 +150,9 @@ void HAL_GetPowerDistributionAllChannelCurrents( /** * Gets the total current of the PowerDistribution. * - * @param handle the module handle - * @return the total current (amps) + * @param[in] handle the module handle + * @param[out] status Error status variable. 0 on success. + * @return the total current (amps) */ double HAL_GetPowerDistributionTotalCurrent(HAL_PowerDistributionHandle handle, int32_t* status); @@ -148,8 +160,9 @@ double HAL_GetPowerDistributionTotalCurrent(HAL_PowerDistributionHandle handle, /** * Gets the total power of the PowerDistribution. * - * @param handle the module handle - * @return the total power (watts) + * @param[in] handle the module handle + * @param[out] status Error status variable. 0 on success. + * @return the total power (watts) */ double HAL_GetPowerDistributionTotalPower(HAL_PowerDistributionHandle handle, int32_t* status); @@ -157,8 +170,9 @@ double HAL_GetPowerDistributionTotalPower(HAL_PowerDistributionHandle handle, /** * Gets the total energy of the PowerDistribution. * - * @param handle the module handle - * @return the total energy (joules) + * @param[in] handle the module handle + * @param[out] status Error status variable. 0 on success. + * @return the total energy (joules) */ double HAL_GetPowerDistributionTotalEnergy(HAL_PowerDistributionHandle handle, int32_t* status); @@ -166,7 +180,8 @@ double HAL_GetPowerDistributionTotalEnergy(HAL_PowerDistributionHandle handle, /** * Resets the PowerDistribution accumulated energy. * - * @param handle the module handle + * @param[in] handle the module handle + * @param[out] status Error status variable. 0 on success. */ void HAL_ResetPowerDistributionTotalEnergy(HAL_PowerDistributionHandle handle, int32_t* status); @@ -174,15 +189,32 @@ void HAL_ResetPowerDistributionTotalEnergy(HAL_PowerDistributionHandle handle, /** * Clears any PowerDistribution sticky faults. * - * @param handle the module handle + * @param[in] handle the module handle + * @param[out] status Error status variable. 0 on success. */ void HAL_ClearPowerDistributionStickyFaults(HAL_PowerDistributionHandle handle, int32_t* status); -// REV PDH Specific functions. This functions will no-op on CTRE PDP +/** + * Power on/off switchable channel. + * + * This is a REV PDH-specific function. This function will no-op on CTRE PDP. + * + * @param[in] handle the module handle + * @param[in] enabled true to turn on switchable channel + * @param[out] status Error status variable. 0 on success. + */ void HAL_SetPowerDistributionSwitchableChannel( HAL_PowerDistributionHandle handle, HAL_Bool enabled, int32_t* status); +/** + * Returns true if switchable channel is powered on. + * + * This is a REV PDH-specific function. This function will no-op on CTRE PDP. + * + * @param[in] handle the module handle + * @param[out] status Error status variable. 0 on success. + */ HAL_Bool HAL_GetPowerDistributionSwitchableChannel( HAL_PowerDistributionHandle handle, int32_t* status); diff --git a/hal/src/main/native/include/hal/Relay.h b/hal/src/main/native/include/hal/Relay.h index d59da0a669..7d711b2421 100644 --- a/hal/src/main/native/include/hal/Relay.h +++ b/hal/src/main/native/include/hal/Relay.h @@ -24,11 +24,13 @@ extern "C" { * Note this call will only initialize either the forward or reverse port of the * relay. If you need both, you will need to initialize 2 relays. * - * @param portHandle the port handle to initialize - * @param fwd true for the forward port, false for the reverse port - * @param allocationLocation the location where the allocation is occuring - * (can be null) - * @return the created relay handle + * @param[in] portHandle the port handle to initialize + * @param[in] fwd true for the forward port, false for the + * reverse port + * @param[in] allocationLocation the location where the allocation is occuring + * (can be null) + * @param[out] status Error status variable. 0 on success. + * @return the created relay handle */ HAL_RelayHandle HAL_InitializeRelayPort(HAL_PortHandle portHandle, HAL_Bool fwd, const char* allocationLocation, @@ -45,15 +47,16 @@ void HAL_FreeRelayPort(HAL_RelayHandle relayPortHandle); * Checks if a relay channel is valid. * * @param channel the channel to check - * @return true if the channel is valid, otherwise false + * @return true if the channel is valid, otherwise false */ HAL_Bool HAL_CheckRelayChannel(int32_t channel); /** * Sets the state of a relay output. * - * @param relayPortHandle the relay handle - * @param on true for on, false for off + * @param[in] relayPortHandle the relay handle + * @param[in] on true for on, false for off + * @param[out] status Error status variable. 0 on success. */ void HAL_SetRelay(HAL_RelayHandle relayPortHandle, HAL_Bool on, int32_t* status); @@ -61,8 +64,9 @@ void HAL_SetRelay(HAL_RelayHandle relayPortHandle, HAL_Bool on, /** * Gets the current state of the relay channel. * - * @param relayPortHandle the relay handle - * @return true for on, false for off + * @param[in] relayPortHandle the relay handle + * @param[out] status Error status variable. 0 on success. + * @return true for on, false for off */ HAL_Bool HAL_GetRelay(HAL_RelayHandle relayPortHandle, int32_t* status); #ifdef __cplusplus diff --git a/hal/src/main/native/include/hal/SPI.h b/hal/src/main/native/include/hal/SPI.h index 70d1d6f519..84cec5ddb9 100644 --- a/hal/src/main/native/include/hal/SPI.h +++ b/hal/src/main/native/include/hal/SPI.h @@ -25,7 +25,9 @@ extern "C" { * * If opening the MXP port, also sets up the channel functions appropriately. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS3, 4 for MXP + * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS3, 4 + * for MXP + * @param[out] status the error code, or 0 for success */ void HAL_InitializeSPI(HAL_SPIPort port, int32_t* status); @@ -36,11 +38,11 @@ void HAL_InitializeSPI(HAL_SPIPort port, int32_t* status); * over each transaction. * * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 - * for MXP + * for MXP * @param dataToSend Buffer of data to send as part of the transaction. * @param dataReceived Buffer to read data into. * @param size Number of bytes to transfer. [0..7] - * @return Number of bytes transferred, -1 for error + * @return Number of bytes transferred, -1 for error */ int32_t HAL_TransactionSPI(HAL_SPIPort port, const uint8_t* dataToSend, uint8_t* dataReceived, int32_t size); @@ -50,11 +52,11 @@ int32_t HAL_TransactionSPI(HAL_SPIPort port, const uint8_t* dataToSend, * * Writes to a device and wait until the transaction is complete. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 - * for MXP - * @param datToSend The data to write to the register on the device. - * @param sendSize The number of bytes to be written - * @return The number of bytes written. -1 for an error + * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP + * @param dataToSend The data to write to the register on the device. + * @param sendSize The number of bytes to be written + * @return The number of bytes written. -1 for an error */ int32_t HAL_WriteSPI(HAL_SPIPort port, const uint8_t* dataToSend, int32_t sendSize); @@ -68,11 +70,11 @@ int32_t HAL_WriteSPI(HAL_SPIPort port, const uint8_t* dataToSend, * begin returning data. * * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for - * MXP + * MXP * @param buffer A pointer to the array of bytes to store the data read from the - * device. + * device. * @param count The number of bytes to read in the transaction. [1..7] - * @return Number of bytes read. -1 for error. + * @return Number of bytes read. -1 for error. */ int32_t HAL_ReadSPI(HAL_SPIPort port, uint8_t* buffer, int32_t count); @@ -87,7 +89,7 @@ void HAL_CloseSPI(HAL_SPIPort port); * Sets the clock speed for the SPI bus. * * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for - * MXP + * MXP * @param speed The speed in Hz (0-1MHz) */ void HAL_SetSPISpeed(HAL_SPIPort port, int32_t speed); @@ -96,12 +98,12 @@ void HAL_SetSPISpeed(HAL_SPIPort port, int32_t speed); * Sets the SPI options. * * @param port The number of the port to use. 0-3 for Onboard - * CS0-CS2, 4 for MXP + * CS0-CS2, 4 for MXP * @param msbFirst True to write the MSB first, False for LSB first * @param sampleOnTrailing True to sample on the trailing edge, False to sample - * on the leading edge + * on the leading edge * @param clkIdleHigh True to set the clock to active low, False to set the - * clock active high + * clock active high */ void HAL_SetSPIOpts(HAL_SPIPort port, HAL_Bool msbFirst, HAL_Bool sampleOnTrailing, HAL_Bool clkIdleHigh); @@ -109,14 +111,18 @@ void HAL_SetSPIOpts(HAL_SPIPort port, HAL_Bool msbFirst, /** * Sets the CS Active high for a SPI port. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP + * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for + * MXP + * @param[out] status the error code, or 0 for success */ void HAL_SetSPIChipSelectActiveHigh(HAL_SPIPort port, int32_t* status); /** * Sets the CS Active low for a SPI port. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP + * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP + * @param[out] status the error code, or 0 for success */ void HAL_SetSPIChipSelectActiveLow(HAL_SPIPort port, int32_t* status); @@ -124,8 +130,8 @@ void HAL_SetSPIChipSelectActiveLow(HAL_SPIPort port, int32_t* status); * Gets the stored handle for a SPI port. * * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for MXP - * @return The stored handle for the SPI port. 0 represents no stored - * handle. + * @return The stored handle for the SPI port. 0 represents no stored + * handle. */ int32_t HAL_GetSPIHandle(HAL_SPIPort port); @@ -133,7 +139,7 @@ int32_t HAL_GetSPIHandle(HAL_SPIPort port); * Sets the stored handle for a SPI port. * * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for - * MXP. + * MXP. * @param handle The value of the handle for the port. */ void HAL_SetSPIHandle(HAL_SPIPort port, int32_t handle); @@ -141,26 +147,29 @@ void HAL_SetSPIHandle(HAL_SPIPort port, int32_t handle); /** * Initializes the SPI automatic accumulator. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 - * for MXP. - * @param bufferSize The accumulator buffer size. + * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, + * 4 for MXP. + * @param[in] bufferSize The accumulator buffer size. + * @param[out] status the error code, or 0 for success */ void HAL_InitSPIAuto(HAL_SPIPort port, int32_t bufferSize, int32_t* status); /** * Frees an SPI automatic accumulator. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for - * MXP. + * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP. + * @param[out] status the error code, or 0 for success */ void HAL_FreeSPIAuto(HAL_SPIPort port, int32_t* status); /** * Sets the period for automatic SPI accumulation. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for - * MXP. - * @param period The accumlation period (seconds). + * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP. + * @param[in] period The accumlation period (seconds). + * @param[out] status the error code, or 0 for success */ void HAL_StartSPIAutoRate(HAL_SPIPort port, double period, int32_t* status); @@ -170,14 +179,15 @@ void HAL_StartSPIAutoRate(HAL_SPIPort port, double period, int32_t* status); * Note that triggering on both rising and falling edges is a valid * configuration. * - * @param port The number of the port to use. 0-3 for Onboard - * CS0-CS2, 4 for MXP. - * @param digitalSourceHandle The trigger source to use (Either - * HAL_AnalogTriggerHandle or HAL_DigitalHandle). - * @param analogTriggerType The analog trigger type, if the source is an - * analog trigger. - * @param triggerRising Trigger on the rising edge if true. - * @param triggerFalling Trigger on the falling edge if true. + * @param[in] port The number of the port to use. 0-3 for Onboard + * CS0-CS2, 4 for MXP. + * @param[in] digitalSourceHandle The trigger source to use (Either + * HAL_AnalogTriggerHandle or HAL_DigitalHandle). + * @param[in] analogTriggerType The analog trigger type, if the source is an + * analog trigger. + * @param[in] triggerRising Trigger on the rising edge if true. + * @param[in] triggerFalling Trigger on the falling edge if true. + * @param[out] status the error code, or 0 for success */ void HAL_StartSPIAutoTrigger(HAL_SPIPort port, HAL_Handle digitalSourceHandle, HAL_AnalogTriggerType analogTriggerType, @@ -187,20 +197,22 @@ void HAL_StartSPIAutoTrigger(HAL_SPIPort port, HAL_Handle digitalSourceHandle, /** * Stops an automatic SPI accumlation. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for - * MXP. + * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP. + * @param[out] status the error code, or 0 for success */ void HAL_StopSPIAuto(HAL_SPIPort port, int32_t* status); /** * Sets the data to be transmitted to the device to initiate a read. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 - * for MXP. - * @param dataToSend Pointer to the data to send (Gets copied for continue use, - * so no need to keep alive). - * @param dataSize The length of the data to send. - * @param zeroSize The number of zeros to send after the data. + * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, + * 4 for MXP. + * @param[in] dataToSend Pointer to the data to send (Gets copied for continue + * use, so no need to keep alive). + * @param[in] dataSize The length of the data to send. + * @param[in] zeroSize The number of zeros to send after the data. + * @param[out] status the error code, or 0 for success */ void HAL_SetSPIAutoTransmitData(HAL_SPIPort port, const uint8_t* dataToSend, int32_t dataSize, int32_t zeroSize, @@ -209,8 +221,9 @@ void HAL_SetSPIAutoTransmitData(HAL_SPIPort port, const uint8_t* dataToSend, /** * Immediately forces an SPI read to happen. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for - * MXP. + * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP. + * @param[out] status the error code, or 0 for success */ void HAL_ForceSPIAutoRead(HAL_SPIPort port, int32_t* status); @@ -221,12 +234,13 @@ void HAL_ForceSPIAutoRead(HAL_SPIPort port, int32_t* status); * sequence is the same as the combined dataSize + zeroSize set in * HAL_SetSPIAutoTransmitData. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 - * for MXP. - * @param buffer The buffer to store the data into. - * @param numToRead The number of words to read. - * @param timeout The read timeout (in seconds). - * @return The number of words actually read. + * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, + * 4 for MXP. + * @param[out] buffer The buffer to store the data into. + * @param[in] numToRead The number of words to read. + * @param[in] timeout The read timeout (in seconds). + * @param[out] status the error code, or 0 for success + * @return The number of words actually read. */ int32_t HAL_ReadSPIAutoReceivedData(HAL_SPIPort port, uint32_t* buffer, int32_t numToRead, double timeout, @@ -235,20 +249,23 @@ int32_t HAL_ReadSPIAutoReceivedData(HAL_SPIPort port, uint32_t* buffer, /** * Gets the count of how many SPI accumulations have been missed. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for - * MXP. - * @return The number of missed accumulations. + * @param[in] port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 + * for MXP. + * @param[out] status the error code, or 0 for success + * @return The number of missed accumulations. */ int32_t HAL_GetSPIAutoDroppedCount(HAL_SPIPort port, int32_t* status); /** * Configure the Auto SPI Stall time between reads. * - * @param port The number of the port to use. 0-3 for Onboard CS0-CS2, 4 for - * MXP. - * @param csToSclkTicks the number of ticks to wait before asserting the cs pin - * @param stallTicks the number of ticks to stall for - * @param pow2BytesPerRead the number of bytes to read before stalling + * @param[in] port The number of the port to use. 0-3 for Onboard + * CS0-CS2, 4 for MXP. + * @param[in] csToSclkTicks the number of ticks to wait before asserting the + * cs pin + * @param[in] stallTicks the number of ticks to stall for + * @param[in] pow2BytesPerRead the number of bytes to read before stalling + * @param[out] status the error code, or 0 for success */ void HAL_ConfigureSPIAutoStall(HAL_SPIPort port, int32_t csToSclkTicks, int32_t stallTicks, int32_t pow2BytesPerRead, diff --git a/hal/src/main/native/include/hal/SerialPort.h b/hal/src/main/native/include/hal/SerialPort.h index f6c33618e0..cd6140e6ef 100644 --- a/hal/src/main/native/include/hal/SerialPort.h +++ b/hal/src/main/native/include/hal/SerialPort.h @@ -33,7 +33,8 @@ extern "C" { * The channels are either the onboard RS232, the mxp uart, or 2 USB ports. The * top port is USB1, the bottom port is USB2. * - * @param port the serial port to initialize + * @param[in] port the serial port to initialize + * @param[out] status the error code, or 0 for success */ HAL_SerialPortHandle HAL_InitializeSerialPort(HAL_SerialPort port, int32_t* status); @@ -44,8 +45,9 @@ HAL_SerialPortHandle HAL_InitializeSerialPort(HAL_SerialPort port, * This name is the /dev name for a specific port. * Note these are not always consistent between roboRIO reboots. * - * @param port the serial port to initialize - * @param portName the dev port name + * @param[in] port the serial port to initialize + * @param[in] portName the dev port name + * @param[out] status the error code, or 0 for success */ HAL_SerialPortHandle HAL_InitializeSerialPortDirect(HAL_SerialPort port, const char* portName, @@ -54,8 +56,9 @@ HAL_SerialPortHandle HAL_InitializeSerialPortDirect(HAL_SerialPort port, /** * Gets the raw serial port file descriptor from a handle. * - * @param handle the serial port handle - * @return the raw port descriptor + * @param[in] handle the serial port handle + * @param[out] status the error code, or 0 for success + * @return the raw port descriptor */ int HAL_GetSerialFD(HAL_SerialPortHandle handle, int32_t* status); @@ -64,8 +67,9 @@ int HAL_GetSerialFD(HAL_SerialPortHandle handle, int32_t* status); * * Any value between 0 and 0xFFFFFFFF may be used. Default is 9600. * - * @param handle the serial port handle - * @param baud the baud rate to set + * @param[in] handle the serial port handle + * @param[in] baud the baud rate to set + * @param[out] status the error code, or 0 for success */ void HAL_SetSerialBaudRate(HAL_SerialPortHandle handle, int32_t baud, int32_t* status); @@ -75,8 +79,9 @@ void HAL_SetSerialBaudRate(HAL_SerialPortHandle handle, int32_t baud, * * Defaults to 8. * - * @param handle the serial port handle - * @param bits the number of data bits (5-8) + * @param[in] handle the serial port handle + * @param[in] bits the number of data bits (5-8) + * @param[out] status the error code, or 0 for success */ void HAL_SetSerialDataBits(HAL_SerialPortHandle handle, int32_t bits, int32_t* status); @@ -91,8 +96,9 @@ void HAL_SetSerialDataBits(HAL_SerialPortHandle handle, int32_t bits, * 3: Mark - Means exists and always 1 * 4: Space - Means exists and always 0 * - * @param handle the serial port handle - * @param parity the parity bit mode (see remarks for valid values) + * @param[in] handle the serial port handle + * @param[in] parity the parity bit mode (see remarks for valid values) + * @param[out] status the error code, or 0 for success */ void HAL_SetSerialParity(HAL_SerialPortHandle handle, int32_t parity, int32_t* status); @@ -105,8 +111,9 @@ void HAL_SetSerialParity(HAL_SerialPortHandle handle, int32_t parity, * 15: One and a half stop bits * 20: Two stop bits * - * @param handle the serial port handle - * @param stopBits the stop bit value (see remarks for valid values) + * @param[in] handle the serial port handle + * @param[in] stopBits the stop bit value (see remarks for valid values) + * @param[out] status the error code, or 0 for success */ void HAL_SetSerialStopBits(HAL_SerialPortHandle handle, int32_t stopBits, int32_t* status); @@ -118,8 +125,9 @@ void HAL_SetSerialStopBits(HAL_SerialPortHandle handle, int32_t stopBits, * 1: Flush on access * 2: Flush when full (default) * - * @param handle the serial port handle - * @param mode the mode to set (see remarks for valid values) + * @param[in] handle the serial port handle + * @param[in] mode the mode to set (see remarks for valid values) + * @param[out] status the error code, or 0 for success */ void HAL_SetSerialWriteMode(HAL_SerialPortHandle handle, int32_t mode, int32_t* status); @@ -133,8 +141,9 @@ void HAL_SetSerialWriteMode(HAL_SerialPortHandle handle, int32_t mode, * 2: RTS-CTS * 3: DTR-DSR * - * @param handle the serial port handle - * @param flow the mode to set (see remarks for valid values) + * @param[in] handle the serial port handle + * @param[in] flow the mode to set (see remarks for valid values) + * @param[out] status the error code, or 0 for success */ void HAL_SetSerialFlowControl(HAL_SerialPortHandle handle, int32_t flow, int32_t* status); @@ -142,8 +151,9 @@ void HAL_SetSerialFlowControl(HAL_SerialPortHandle handle, int32_t flow, /** * Sets the minimum serial read timeout of a port. * - * @param handle the serial port handle - * @param timeout the timeout in milliseconds + * @param[in] handle the serial port handle + * @param[in] timeout the timeout in milliseconds + * @param[out] status the error code, or 0 for success */ void HAL_SetSerialTimeout(HAL_SerialPortHandle handle, double timeout, int32_t* status); @@ -153,8 +163,9 @@ void HAL_SetSerialTimeout(HAL_SerialPortHandle handle, double timeout, * * By default this is disabled. * - * @param handle the serial port handle - * @param terminator the termination character to set + * @param[in] handle the serial port handle + * @param[in] terminator the termination character to set + * @param[out] status the error code, or 0 for success */ void HAL_EnableSerialTermination(HAL_SerialPortHandle handle, char terminator, int32_t* status); @@ -162,15 +173,17 @@ void HAL_EnableSerialTermination(HAL_SerialPortHandle handle, char terminator, /** * Disables a termination character for reads. * - * @param handle the serial port handle + * @param[in] handle the serial port handle + * @param[out] status the error code, or 0 for success */ void HAL_DisableSerialTermination(HAL_SerialPortHandle handle, int32_t* status); /** * Sets the size of the read buffer. * - * @param handle the serial port handle - * @param size the read buffer size + * @param[in] handle the serial port handle + * @param[in] size the read buffer size + * @param[out] status the error code, or 0 for success */ void HAL_SetSerialReadBufferSize(HAL_SerialPortHandle handle, int32_t size, int32_t* status); @@ -178,8 +191,9 @@ void HAL_SetSerialReadBufferSize(HAL_SerialPortHandle handle, int32_t size, /** * Sets the size of the write buffer. * - * @param handle the serial port handle - * @param size the write buffer size + * @param[in] handle the serial port handle + * @param[in] size the write buffer size + * @param[out] status the error code, or 0 for success */ void HAL_SetSerialWriteBufferSize(HAL_SerialPortHandle handle, int32_t size, int32_t* status); @@ -187,8 +201,9 @@ void HAL_SetSerialWriteBufferSize(HAL_SerialPortHandle handle, int32_t size, /** * Gets the number of bytes currently in the read buffer. * - * @param handle the serial port handle - * @return the number of bytes in the read buffer + * @param[in] handle the serial port handle + * @param[out] status the error code, or 0 for success + * @return the number of bytes in the read buffer */ int32_t HAL_GetSerialBytesReceived(HAL_SerialPortHandle handle, int32_t* status); @@ -199,9 +214,11 @@ int32_t HAL_GetSerialBytesReceived(HAL_SerialPortHandle handle, * Will wait for either timeout (if set), the termination char (if set), or the * count to be full. Whichever one comes first. * - * @param handle the serial port handle - * @param count the number of bytes maximum to read - * @return the number of bytes actually read + * @param[in] handle the serial port handle + * @param[out] buffer the buffer in which to store bytes read + * @param[in] count the number of bytes maximum to read + * @param[out] status the error code, or 0 for success + * @return the number of bytes actually read */ int32_t HAL_ReadSerial(HAL_SerialPortHandle handle, char* buffer, int32_t count, int32_t* status); @@ -209,10 +226,11 @@ int32_t HAL_ReadSerial(HAL_SerialPortHandle handle, char* buffer, int32_t count, /** * Writes data to the serial port. * - * @param handle the serial port handle - * @param buffer the buffer to write - * @param count the number of bytes to write from the buffer - * @return the number of bytes actually written + * @param[in] handle the serial port handle + * @param[in] buffer the buffer to write + * @param[in] count the number of bytes to write from the buffer + * @param[out] status the error code, or 0 for success + * @return the number of bytes actually written */ int32_t HAL_WriteSerial(HAL_SerialPortHandle handle, const char* buffer, int32_t count, int32_t* status); @@ -220,21 +238,24 @@ int32_t HAL_WriteSerial(HAL_SerialPortHandle handle, const char* buffer, /** * Flushes the serial write buffer out to the port. * - * @param handle the serial port handle + * @param[in] handle the serial port handle + * @param[out] status the error code, or 0 for success */ void HAL_FlushSerial(HAL_SerialPortHandle handle, int32_t* status); /** * Clears the receive buffer of the serial port. * - * @param handle the serial port handle + * @param[in] handle the serial port handle + * @param[out] status the error code, or 0 for success */ void HAL_ClearSerial(HAL_SerialPortHandle handle, int32_t* status); /** * Closes a serial port. * - * @param handle the serial port handle to close + * @param[in] handle the serial port handle to close + * @param[out] status the error code, or 0 for success */ void HAL_CloseSerial(HAL_SerialPortHandle handle, int32_t* status); #ifdef __cplusplus diff --git a/hal/src/main/native/include/hal/Threads.h b/hal/src/main/native/include/hal/Threads.h index e857dc57a2..a6db5e0ee1 100644 --- a/hal/src/main/native/include/hal/Threads.h +++ b/hal/src/main/native/include/hal/Threads.h @@ -21,13 +21,13 @@ extern "C" { /** * Gets the thread priority for the specified thread. * - * @param handle Native handle pointer to the thread to get the priority - * for. - * @param isRealTime Set to true if thread is real-time, otherwise false. - * @param status Error status variable. 0 on success. - * @return The current thread priority. For real-time, this is 1-99 - * with 99 being highest. For non-real-time, this is 0. See - * "man 7 sched" for details. + * @param[in] handle Native handle pointer to the thread to get the + * priority for. + * @param[out] isRealTime Set to true if thread is real-time, otherwise false. + * @param[out] status Error status variable. 0 on success. + * @return The current thread priority. For real-time, this is 1-99 with 99 + * being highest. For non-real-time, this is 0. See "man 7 sched" for + * details. */ int32_t HAL_GetThreadPriority(NativeThreadHandle handle, HAL_Bool* isRealTime, int32_t* status); @@ -35,26 +35,25 @@ int32_t HAL_GetThreadPriority(NativeThreadHandle handle, HAL_Bool* isRealTime, /** * Gets the thread priority for the current thread. * - * @param handle Native handle pointer to the thread to get the priority for - * @param isRealTime Set to true if thread is real-time, otherwise false. - * @param status Error status variable. 0 on success. - * @return The current thread priority. For real-time, this is 1-99 - * with 99 being highest. For non-real-time, this is 0. See - * "man 7 sched" for details. + * @param[out] isRealTime Set to true if thread is real-time, otherwise false. + * @param[out] status Error status variable. 0 on success. + * @return The current thread priority. For real-time, this is 1-99 with 99 + * being highest. For non-real-time, this is 0. See "man 7 sched" for + * details. */ int32_t HAL_GetCurrentThreadPriority(HAL_Bool* isRealTime, int32_t* status); /** * Sets the thread priority for the specified thread. * - * @param thread Reference to the thread to set the priority of. - * @param realTime Set to true to set a real-time priority, false for standard - * priority. - * @param priority Priority to set the thread to. For real-time, this is 1-99 - * with 99 being highest. For non-real-time, this is forced to - * 0. See "man 7 sched" for more details. - * @param status Error status variable. 0 on success. - * @return True on success. + * @param[in] handle Reference to the thread to set the priority of. + * @param[in] realTime Set to true to set a real-time priority, false for + * standard priority. + * @param[in] priority Priority to set the thread to. For real-time, this is + * 1-99 with 99 being highest. For non-real-time, this is + * forced to 0. See "man 7 sched" for more details. + * @param[out] status Error status variable. 0 on success. + * @return True on success. */ HAL_Bool HAL_SetThreadPriority(NativeThreadHandle handle, HAL_Bool realTime, int32_t priority, int32_t* status); @@ -62,14 +61,13 @@ HAL_Bool HAL_SetThreadPriority(NativeThreadHandle handle, HAL_Bool realTime, /** * Sets the thread priority for the current thread. * - * @param thread Reference to the thread to set the priority of. - * @param realTime Set to true to set a real-time priority, false for standard - * priority. - * @param priority Priority to set the thread to. For real-time, this is 1-99 - * with 99 being highest. For non-real-time, this is forced to - * 0. See "man 7 sched" for more details. - * @param status Error status variable. 0 on success. - * @return True on success. + * @param[in] realTime Set to true to set a real-time priority, false for + * standard priority. + * @param[in] priority Priority to set the thread to. For real-time, this is + * 1-99 with 99 being highest. For non-real-time, this is + * forced to 0. See "man 7 sched" for more details. + * @param[out] status Error status variable. 0 on success. + * @return True on success. */ HAL_Bool HAL_SetCurrentThreadPriority(HAL_Bool realTime, int32_t priority, int32_t* status); diff --git a/hal/src/main/native/include/hal/cpp/SerialHelper.h b/hal/src/main/native/include/hal/cpp/SerialHelper.h index 2c956e3a10..13b6857d5a 100644 --- a/hal/src/main/native/include/hal/cpp/SerialHelper.h +++ b/hal/src/main/native/include/hal/cpp/SerialHelper.h @@ -26,34 +26,34 @@ class SerialHelper { /** * Get the VISA name of a serial port. * - * @param port the serial port index - * @param status status check - * @return the VISA name + * @param[in] port the serial port index + * @param[out] status status check + * @return the VISA name */ std::string GetVISASerialPortName(HAL_SerialPort port, int32_t* status); /** * Get the OS name of a serial port. * - * @param port the serial port index - * @param status status check - * @return the OS name + * @param[in] port the serial port index + * @param[out] status status check + * @return the OS name */ std::string GetOSSerialPortName(HAL_SerialPort port, int32_t* status); /** * Get a vector of all serial port VISA names. * - * @param status status check - * @return vector of serial port VISA names + * @param[out] status status check + * @return vector of serial port VISA names */ std::vector GetVISASerialPortList(int32_t* status); /** * Get a vector of all serial port OS names. * - * @param status status check - * @return vector of serial port OS names + * @param[out] status status check + * @return vector of serial port OS names */ std::vector GetOSSerialPortList(int32_t* status); diff --git a/hal/src/main/native/include/hal/cpp/UnsafeDIO.h b/hal/src/main/native/include/hal/cpp/UnsafeDIO.h index ffd4b33451..eb7f231301 100644 --- a/hal/src/main/native/include/hal/cpp/UnsafeDIO.h +++ b/hal/src/main/native/include/hal/cpp/UnsafeDIO.h @@ -58,9 +58,9 @@ int32_t ComputeDigitalMask(HAL_DigitalHandle handle, int32_t* status); * functions on the Proxy object passed as a parameter can deadlock your * program. * - * @param handle the HAL digital handle of the pin to toggle. - * @param status status check - * @param func A functor taking a ref to a DIOSetProxy object. + * @param[in] handle the HAL digital handle of the pin to toggle. + * @param[out] status status check + * @param[in] func A functor taking a ref to a DIOSetProxy object. */ template void UnsafeManipulateDIO(HAL_DigitalHandle handle, int32_t* status, diff --git a/hal/src/main/native/include/hal/handles/HandlesInternal.h b/hal/src/main/native/include/hal/handles/HandlesInternal.h index 3307a0792c..6127c63fb0 100644 --- a/hal/src/main/native/include/hal/handles/HandlesInternal.h +++ b/hal/src/main/native/include/hal/handles/HandlesInternal.h @@ -76,7 +76,7 @@ enum class HAL_HandleEnum { * Get the handle index from a handle. * * @param handle the handle - * @return the index + * @return the index */ static inline int16_t getHandleIndex(HAL_Handle handle) { // mask and return last 16 bits @@ -87,7 +87,7 @@ static inline int16_t getHandleIndex(HAL_Handle handle) { * Get the handle type from a handle. * * @param handle the handle - * @return the type + * @return the type */ static inline HAL_HandleEnum getHandleType(HAL_Handle handle) { // mask first 8 bits and cast to enum @@ -99,7 +99,7 @@ static inline HAL_HandleEnum getHandleType(HAL_Handle handle) { * * @param handle the handle * @param handleType the type to check - * @return true if the type is correct, otherwise false + * @return true if the type is correct, otherwise false */ static inline bool isHandleType(HAL_Handle handle, HAL_HandleEnum handleType) { return handleType == getHandleType(handle); @@ -112,7 +112,7 @@ static inline bool isHandleType(HAL_Handle handle, HAL_HandleEnum handleType) { * * @param handle the handle * @param version the handle version to check - * @return true if the handle is the right version, otherwise false + * @return true if the handle is the right version, otherwise false */ static inline bool isHandleCorrectVersion(HAL_Handle handle, int16_t version) { return (((handle & 0xFF0000) >> 16) & version) == version; @@ -124,10 +124,10 @@ static inline bool isHandleCorrectVersion(HAL_Handle handle, int16_t version) { * Note the version is not checked on the roboRIO. * * @param handle the handle - * @param handleType the type to check + * @param enumType the type to check * @param version the handle version to check - * @return true if the handle is proper version and type, otherwise - * false. + * @return true if the handle is proper version and type, otherwise + * false. */ inline int16_t getHandleTypedIndex(HAL_Handle handle, HAL_HandleEnum enumType, int16_t version) { @@ -156,7 +156,7 @@ inline int16_t getHandleTypedIndex(HAL_Handle handle, HAL_HandleEnum enumType, * Gets the port channel of a port handle. * * @param handle the port handle - * @return the port channel + * @return the port channel */ inline int16_t getPortHandleChannel(HAL_PortHandle handle) { if (!isHandleType(handle, HAL_HandleEnum::Port)) { @@ -170,7 +170,7 @@ inline int16_t getPortHandleChannel(HAL_PortHandle handle) { * Gets the port module of a port handle. * * @param handle the port handle - * @return the port module + * @return the port module */ inline int16_t getPortHandleModule(HAL_PortHandle handle) { if (!isHandleType(handle, HAL_HandleEnum::Port)) { @@ -184,7 +184,7 @@ inline int16_t getPortHandleModule(HAL_PortHandle handle) { * Gets the SPI channel of a port handle. * * @param handle the port handle - * @return the port SPI channel + * @return the port SPI channel */ inline int16_t getPortHandleSPIEnable(HAL_PortHandle handle) { if (!isHandleType(handle, HAL_HandleEnum::Port)) { @@ -198,7 +198,7 @@ inline int16_t getPortHandleSPIEnable(HAL_PortHandle handle) { * * @param channel the channel * @param module the module - * @return port handle for the module and channel + * @return port handle for the module and channel */ HAL_PortHandle createPortHandle(uint8_t channel, uint8_t module); @@ -206,7 +206,7 @@ HAL_PortHandle createPortHandle(uint8_t channel, uint8_t module); * Create a port handle for SPI. * * @param channel the SPI channel - * @return port handle for the channel + * @return port handle for the channel */ HAL_PortHandle createPortHandleForSPI(uint8_t channel); @@ -218,7 +218,7 @@ HAL_PortHandle createPortHandleForSPI(uint8_t channel); * @param index the index * @param handleType the handle type * @param version the handle version - * @return the created handle + * @return the created handle */ HAL_Handle createHandle(int16_t index, HAL_HandleEnum handleType, int16_t version); diff --git a/hal/src/main/native/sim/HAL.cpp b/hal/src/main/native/sim/HAL.cpp index 7910ccf657..8d911df7fe 100644 --- a/hal/src/main/native/sim/HAL.cpp +++ b/hal/src/main/native/sim/HAL.cpp @@ -280,10 +280,10 @@ uint64_t HAL_GetFPGATime(int32_t* status) { return hal::GetFPGATime(); } -uint64_t HAL_ExpandFPGATime(uint32_t unexpanded_lower, int32_t* status) { +uint64_t HAL_ExpandFPGATime(uint32_t unexpandedLower, int32_t* status) { // Capture the current FPGA time. This will give us the upper half of the // clock. - uint64_t fpga_time = HAL_GetFPGATime(status); + uint64_t fpgaTime = HAL_GetFPGATime(status); if (*status != 0) { return 0; } @@ -293,15 +293,15 @@ uint64_t HAL_ExpandFPGATime(uint32_t unexpanded_lower, int32_t* status) { // be. // Break it into lower and upper portions. - uint32_t lower = fpga_time & 0xffffffffull; - uint64_t upper = (fpga_time >> 32) & 0xffffffff; + uint32_t lower = fpgaTime & 0xffffffffull; + uint64_t upper = (fpgaTime >> 32) & 0xffffffff; // The time was sampled *before* the current time, so roll it back. - if (lower < unexpanded_lower) { + if (lower < unexpandedLower) { --upper; } - return (upper << 32) + static_cast(unexpanded_lower); + return (upper << 32) + static_cast(unexpandedLower); } HAL_Bool HAL_GetFPGAButton(int32_t* status) { diff --git a/ntcore/src/main/native/cpp/ntcore_cpp.cpp b/ntcore/src/main/native/cpp/ntcore_cpp.cpp index ae85e46b26..8616aafe77 100644 --- a/ntcore/src/main/native/cpp/ntcore_cpp.cpp +++ b/ntcore/src/main/native/cpp/ntcore_cpp.cpp @@ -1059,18 +1059,18 @@ const char* LoadEntries( NT_Logger AddLogger(NT_Inst inst, std::function func, - unsigned int min_level, unsigned int max_level) { + unsigned int minLevel, unsigned int maxLevel) { int i = Handle{inst}.GetTypedInst(Handle::kInstance); auto ii = InstanceImpl::Get(i); if (!ii) { return 0; } - if (min_level < ii->logger.min_level()) { - ii->logger.set_min_level(min_level); + if (minLevel < ii->logger.min_level()) { + ii->logger.set_min_level(minLevel); } - return Handle(i, ii->logger_impl.Add(func, min_level, max_level), + return Handle(i, ii->logger_impl.Add(func, minLevel, maxLevel), Handle::kLogger); } diff --git a/ntcore/src/main/native/include/networktables/NetworkTableEntry.h b/ntcore/src/main/native/include/networktables/NetworkTableEntry.h index ff717ae583..c6c9c86a59 100644 --- a/ntcore/src/main/native/include/networktables/NetworkTableEntry.h +++ b/ntcore/src/main/native/include/networktables/NetworkTableEntry.h @@ -242,7 +242,7 @@ class NetworkTableEntry final { /** * Sets the entry's value if it does not exist. * - * @param defaultValue the default value to set + * @param value the default value to set * @return False if the entry exists with a different type */ bool SetDefaultValue(std::shared_ptr value); diff --git a/ntcore/src/main/native/include/networktables/NetworkTableInstance.h b/ntcore/src/main/native/include/networktables/NetworkTableInstance.h index f91efa0857..54b5324854 100644 --- a/ntcore/src/main/native/include/networktables/NetworkTableInstance.h +++ b/ntcore/src/main/native/include/networktables/NetworkTableInstance.h @@ -85,7 +85,7 @@ class NetworkTableInstance final { /** * Construct from native handle. * - * @param handle Native handle + * @param inst Native handle */ explicit NetworkTableInstance(NT_Inst inst) noexcept; @@ -523,7 +523,7 @@ class NetworkTableInstance final { * @return Logger handle */ NT_Logger AddLogger(std::function func, - unsigned int min_level, unsigned int max_level); + unsigned int minLevel, unsigned int maxLevel); /** * Remove a logger. diff --git a/ntcore/src/main/native/include/ntcore_c.h b/ntcore/src/main/native/include/ntcore_c.h index 9556b6b769..3ee6d51889 100644 --- a/ntcore/src/main/native/include/ntcore_c.h +++ b/ntcore/src/main/native/include/ntcore_c.h @@ -325,11 +325,13 @@ NT_Entry NT_GetEntry(NT_Inst inst, const char* name, size_t name_len); * filtered by string prefix and entry type to only return a subset of all * entries. * - * @param prefix entry name required prefix; only entries whose name - * starts with this string are returned - * @param prefix_len length of prefix in bytes - * @param types bitmask of NT_Type values; 0 is treated specially - * as a "don't care" + * @param inst NetworkTable instance + * @param prefix entry name required prefix; only entries whose name starts + * with this string are returned + * @param prefix_len length of prefix in bytes + * @param types bitmask of NT_Type values; 0 is treated specially as a + * "don't care" + * @param count stores number of entry handles returned * @return Array of entry handles. */ NT_Entry* NT_GetEntries(NT_Inst inst, const char* prefix, size_t prefix_len, @@ -570,6 +572,7 @@ void NT_DestroyEntryListenerPoller(NT_EntryListenerPoller poller); * * @param poller poller handle * @param prefix UTF-8 string prefix + * @param prefix_len Length of UTF-8 string prefix * @param flags NT_NotifyKind bitmask * @return Listener handle */ @@ -583,7 +586,7 @@ NT_EntryListener NT_AddPolledEntryListener(NT_EntryListenerPoller poller, * The caller is responsible for calling NT_PollEntryListener() to poll. * * @param poller poller handle - * @param prefix UTF-8 string prefix + * @param entry entry handle * @param flags NT_NotifyKind bitmask * @return Listener handle */ @@ -1592,21 +1595,21 @@ struct NT_String* NT_AllocateStringArray(size_t size); /** * Frees an array of chars. * - * @param v_boolean pointer to the char array to free + * @param v_char pointer to the char array to free */ void NT_FreeCharArray(char* v_char); /** * Frees an array of doubles. * - * @param v_boolean pointer to the double array to free + * @param v_double pointer to the double array to free */ void NT_FreeDoubleArray(double* v_double); /** * Frees an array of booleans. * - * @param v_boolean pointer to the boolean array to free + * @param v_boolean pointer to the boolean array to free */ void NT_FreeBooleanArray(NT_Bool* v_boolean); diff --git a/ntcore/src/main/native/include/ntcore_cpp.h b/ntcore/src/main/native/include/ntcore_cpp.h index c946f4cf98..2d91fe5b38 100644 --- a/ntcore/src/main/native/include/ntcore_cpp.h +++ b/ntcore/src/main/native/include/ntcore_cpp.h @@ -585,7 +585,7 @@ NT_EntryListener AddPolledEntryListener(NT_EntryListenerPoller poller, * The caller is responsible for calling PollEntryListener() to poll. * * @param poller poller handle - * @param prefix UTF-8 string prefix + * @param entry entry handle * @param flags NotifyKind bitmask * @return Listener handle */ diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/Command.h b/wpilibNewCommands/src/main/native/include/frc2/command/Command.h index 9f507b5fb3..66f4f7e012 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/Command.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/Command.h @@ -211,11 +211,9 @@ class Command { bool IsScheduled() const; /** - * Whether the command requires a given subsystem. Named "hasRequirement" - * rather than "requires" to avoid confusion with - * {@link - * edu.wpi.first.wpilibj.command.Command#requires(edu.wpi.first.wpilibj.command.Subsystem)} - * - this may be able to be changed in a few years. + * Whether the command requires a given subsystem. Named "HasRequirement" + * rather than "requires" to avoid confusion with Command::Requires(Subsystem) + * -- this may be able to be changed in a few years. * * @param requirement the subsystem to inquire about * @return whether the subsystem is required diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/CommandGroupBase.h b/wpilibNewCommands/src/main/native/include/frc2/command/CommandGroupBase.h index 0ba17d7d16..6a84ee0b79 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/CommandGroupBase.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/CommandGroupBase.h @@ -46,7 +46,8 @@ class CommandGroupBase : public CommandBase { * @param commands The commands to check * @return True if all the commands are ungrouped. */ - static bool RequireUngrouped(wpi::span>); + static bool RequireUngrouped( + wpi::span> commands); /** * Requires that the specified commands not have been already allocated to a @@ -55,7 +56,7 @@ class CommandGroupBase : public CommandBase { * @param commands The commands to check * @return True if all the commands are ungrouped. */ - static bool RequireUngrouped(std::initializer_list); + static bool RequireUngrouped(std::initializer_list commands); /** * Adds the given commands to the command group. diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/CommandScheduler.h b/wpilibNewCommands/src/main/native/include/frc2/command/CommandScheduler.h index 71f833b671..8976e852d2 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/CommandScheduler.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/CommandScheduler.h @@ -209,7 +209,7 @@ class CommandScheduler final : public nt::NTSendable, *

Commands will be canceled even if they are not scheduled as * interruptible. * - * @param commands the commands to cancel + * @param command the command to cancel */ void Cancel(Command* command); @@ -278,7 +278,7 @@ class CommandScheduler final : public nt::NTSendable, * that are directly scheduled by the scheduler; it will not work on commands * inside of CommandGroups, as the scheduler does not see them. * - * @param commands the command to query + * @param command the command to query * @return whether the command is currently scheduled */ bool IsScheduled(const Command* command) const; diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/NotifierCommand.h b/wpilibNewCommands/src/main/native/include/frc2/command/NotifierCommand.h index f4f31e3790..ec68fe7ed5 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/NotifierCommand.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/NotifierCommand.h @@ -17,9 +17,9 @@ namespace frc2 { /** * A command that starts a notifier to run the given runnable periodically in a - * separate thread. Has no end condition as-is; either subclass it or use {@link - * Command#withTimeout(double)} or - * {@link Command#withInterrupt(BooleanSupplier)} to give it one. + * separate thread. Has no end condition as-is; either subclass it or use + * Command::WithTimeout(double) or Command::WithInterrupt(BooleanSupplier) to + * give it one. * *

WARNING: Do not use this class unless you are confident in your ability to * make the executed code thread-safe. If you do not know what "thread-safe" diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/SubsystemBase.h b/wpilibNewCommands/src/main/native/include/frc2/command/SubsystemBase.h index ddcecaca48..748271a5a0 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/SubsystemBase.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/SubsystemBase.h @@ -47,7 +47,7 @@ class SubsystemBase : public Subsystem, /** * Sets the subsystem name of this Subsystem. * - * @param subsystem subsystem name + * @param name subsystem name */ void SetSubsystem(std::string_view name); diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/TrapezoidProfileCommand.h b/wpilibNewCommands/src/main/native/include/frc2/command/TrapezoidProfileCommand.h index 4cfbd23177..1d8d2c5936 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/TrapezoidProfileCommand.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/TrapezoidProfileCommand.h @@ -35,8 +35,9 @@ class TrapezoidProfileCommand * Creates a new TrapezoidProfileCommand that will execute the given * TrapezoidalProfile. Output will be piped to the provided consumer function. * - * @param profile The motion profile to execute. - * @param output The consumer for the profile output. + * @param profile The motion profile to execute. + * @param output The consumer for the profile output. + * @param requirements The list of requirements. */ TrapezoidProfileCommand(frc::TrapezoidProfile profile, std::function output, @@ -49,8 +50,9 @@ class TrapezoidProfileCommand * Creates a new TrapezoidProfileCommand that will execute the given * TrapezoidalProfile. Output will be piped to the provided consumer function. * - * @param profile The motion profile to execute. - * @param output The consumer for the profile output. + * @param profile The motion profile to execute. + * @param output The consumer for the profile output. + * @param requirements The list of requirements. */ TrapezoidProfileCommand(frc::TrapezoidProfile profile, std::function output, diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/button/Button.h b/wpilibNewCommands/src/main/native/include/frc2/command/button/Button.h index 3540432a53..bab7a0fb1d 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/button/Button.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/button/Button.h @@ -25,7 +25,7 @@ class Button : public Trigger { /** * Create a new button that is pressed when the given condition is true. * - * @param isActive Whether the button is pressed. + * @param isPressed Whether the button is pressed. */ explicit Button(std::function isPressed); diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/button/Trigger.h b/wpilibNewCommands/src/main/native/include/frc2/command/button/Trigger.h index 3c1d8f90ad..3213d4b226 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/button/Trigger.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/button/Trigger.h @@ -90,7 +90,7 @@ class Trigger { * Binds a runnable to execute when the trigger becomes active. * * @param toRun the runnable to execute. - * @paaram requirements the required subsystems. + * @param requirements the required subsystems. */ Trigger WhenActive(std::function toRun, std::initializer_list requirements); @@ -99,7 +99,7 @@ class Trigger { * Binds a runnable to execute when the trigger becomes active. * * @param toRun the runnable to execute. - * @paaram requirements the required subsystems. + * @param requirements the required subsystems. */ Trigger WhenActive(std::function toRun, wpi::span requirements = {}); diff --git a/wpilibOldCommands/src/main/native/include/frc/PIDBase.h b/wpilibOldCommands/src/main/native/include/frc/PIDBase.h index 60f6991297..e834006a24 100644 --- a/wpilibOldCommands/src/main/native/include/frc/PIDBase.h +++ b/wpilibOldCommands/src/main/native/include/frc/PIDBase.h @@ -40,9 +40,9 @@ class PIDBase : public PIDInterface, /** * Allocate a PID object with the given constants for P, I, D. * - * @param Kp the proportional coefficient - * @param Ki the integral coefficient - * @param Kd the derivative coefficient + * @param p the proportional coefficient + * @param i the integral coefficient + * @param d the derivative coefficient * @param source The PIDSource object that is used to get values * @param output The PIDOutput object that is set to the output value */ @@ -52,9 +52,10 @@ class PIDBase : public PIDInterface, /** * Allocate a PID object with the given constants for P, I, D. * - * @param Kp the proportional coefficient - * @param Ki the integral coefficient - * @param Kd the derivative coefficient + * @param p the proportional coefficient + * @param i the integral coefficient + * @param d the derivative coefficient + * @param f the feedforward coefficient * @param source The PIDSource object that is used to get values * @param output The PIDOutput object that is set to the output value */ @@ -235,7 +236,7 @@ class PIDBase : public PIDInterface, * Set the percentage error which is considered tolerable for use with * OnTarget. * - * @param percentage error which is tolerable + * @param percent error which is tolerable */ WPI_DEPRECATED("Use SetPercentTolerance() instead.") virtual void SetTolerance(double percent); @@ -244,17 +245,17 @@ class PIDBase : public PIDInterface, * Set the absolute error which is considered tolerable for use with * OnTarget. * - * @param percentage error which is tolerable + * @param absTolerance error which is tolerable */ - virtual void SetAbsoluteTolerance(double absValue); + virtual void SetAbsoluteTolerance(double absTolerance); /** * Set the percentage error which is considered tolerable for use with * OnTarget. * - * @param percentage error which is tolerable + * @param percent error which is tolerable */ - virtual void SetPercentTolerance(double percentValue); + virtual void SetPercentTolerance(double percent); /** * Set the number of previous error samples to average for tolerancing. When @@ -267,7 +268,7 @@ class PIDBase : public PIDInterface, * @param bufLength Number of previous cycles to average. Defaults to 1. */ WPI_DEPRECATED("Use a LinearDigitalFilter as the input.") - virtual void SetToleranceBuffer(int buf = 1); + virtual void SetToleranceBuffer(int bufLength = 1); /** * Return true if the error is within the percentage of the total input range, diff --git a/wpilibOldCommands/src/main/native/include/frc/PIDController.h b/wpilibOldCommands/src/main/native/include/frc/PIDController.h index cd932dd5e6..763752de15 100644 --- a/wpilibOldCommands/src/main/native/include/frc/PIDController.h +++ b/wpilibOldCommands/src/main/native/include/frc/PIDController.h @@ -37,9 +37,9 @@ class PIDController : public PIDBase, public Controller { /** * Allocate a PID object with the given constants for P, I, D. * - * @param Kp the proportional coefficient - * @param Ki the integral coefficient - * @param Kd the derivative coefficient + * @param p the proportional coefficient + * @param i the integral coefficient + * @param d the derivative coefficient * @param source The PIDSource object that is used to get values * @param output The PIDOutput object that is set to the output value * @param period the loop time for doing calculations in seconds. This @@ -53,9 +53,10 @@ class PIDController : public PIDBase, public Controller { /** * Allocate a PID object with the given constants for P, I, D. * - * @param Kp the proportional coefficient - * @param Ki the integral coefficient - * @param Kd the derivative coefficient + * @param p the proportional coefficient + * @param i the integral coefficient + * @param d the derivative coefficient + * @param f the feedforward coefficient * @param source The PIDSource object that is used to get values * @param output The PIDOutput object that is set to the output value * @param period the loop time for doing calculations in seconds. This @@ -69,9 +70,9 @@ class PIDController : public PIDBase, public Controller { /** * Allocate a PID object with the given constants for P, I, D. * - * @param Kp the proportional coefficient - * @param Ki the integral coefficient - * @param Kd the derivative coefficient + * @param p the proportional coefficient + * @param i the integral coefficient + * @param d the derivative coefficient * @param source The PIDSource object that is used to get values * @param output The PIDOutput object that is set to the output value * @param period the loop time for doing calculations in seconds. This @@ -85,9 +86,10 @@ class PIDController : public PIDBase, public Controller { /** * Allocate a PID object with the given constants for P, I, D. * - * @param Kp the proportional coefficient - * @param Ki the integral coefficient - * @param Kd the derivative coefficient + * @param p the proportional coefficient + * @param i the integral coefficient + * @param d the derivative coefficient + * @param f the feedforward coefficient * @param source The PIDSource object that is used to get values * @param output The PIDOutput object that is set to the output value * @param period the loop time for doing calculations in seconds. This diff --git a/wpilibOldCommands/src/main/native/include/frc/buttons/Trigger.h b/wpilibOldCommands/src/main/native/include/frc/buttons/Trigger.h index f75713c381..966a29f80f 100644 --- a/wpilibOldCommands/src/main/native/include/frc/buttons/Trigger.h +++ b/wpilibOldCommands/src/main/native/include/frc/buttons/Trigger.h @@ -23,8 +23,8 @@ class Command; * It is encouraged that teams write a subclass of Trigger if they want to have * something unusual (for instance, if they want to react to the user holding * a button while the robot is reading a certain sensor input). For this, they - * only have to write the {@link Trigger#Get()} method to get the full - * functionality of the Trigger class. + * only have to write the Trigger::Get() method to get the full functionality of + * the Trigger class. */ class Trigger : public wpi::Sendable, public wpi::SendableHelper { public: diff --git a/wpilibOldCommands/src/main/native/include/frc/commands/Command.h b/wpilibOldCommands/src/main/native/include/frc/commands/Command.h index aa7d5d042e..aa20134e96 100644 --- a/wpilibOldCommands/src/main/native/include/frc/commands/Command.h +++ b/wpilibOldCommands/src/main/native/include/frc/commands/Command.h @@ -135,7 +135,7 @@ class Command : public wpi::Sendable, public wpi::SendableHelper { * @param subsystem The Subsystem required * @see Subsystem */ - void Requires(Subsystem* s); + void Requires(Subsystem* subsystem); /** * Starts up the command. Gets the command ready to start. @@ -214,7 +214,7 @@ class Command : public wpi::Sendable, public wpi::SendableHelper { /** * Checks if the command requires the given Subsystem. * - * @param system the system + * @param subsystem the subsystem * @return whether or not the subsystem is required (false if given nullptr) */ bool DoesRequire(Subsystem* subsystem) const; diff --git a/wpilibOldCommands/src/main/native/include/frc/commands/Scheduler.h b/wpilibOldCommands/src/main/native/include/frc/commands/Scheduler.h index 68285d2c4d..ad82f63dfd 100644 --- a/wpilibOldCommands/src/main/native/include/frc/commands/Scheduler.h +++ b/wpilibOldCommands/src/main/native/include/frc/commands/Scheduler.h @@ -42,7 +42,7 @@ class Scheduler : public nt::NTSendable, public wpi::SendableHelper { * * All Subsystems should call this. * - * @param system the system + * @param subsystem the system */ void RegisterSubsystem(Subsystem* subsystem); diff --git a/wpilibOldCommands/src/main/native/include/frc/commands/Subsystem.h b/wpilibOldCommands/src/main/native/include/frc/commands/Subsystem.h index bdf1ee858c..8c18d5c66d 100644 --- a/wpilibOldCommands/src/main/native/include/frc/commands/Subsystem.h +++ b/wpilibOldCommands/src/main/native/include/frc/commands/Subsystem.h @@ -148,21 +148,21 @@ class Subsystem : public wpi::Sendable, public wpi::SendableHelper { void AddChild(std::string_view name, wpi::Sendable& child); /** - * Associate a {@link Sendable} with this Subsystem. + * Associate a Sendable with this Subsystem. * * @param child sendable */ void AddChild(std::shared_ptr child); /** - * Associate a {@link Sendable} with this Subsystem. + * Associate a Sendable with this Subsystem. * * @param child sendable */ void AddChild(wpi::Sendable* child); /** - * Associate a {@link Sendable} with this Subsystem. + * Associate a Sendable with this Subsystem. * * @param child sendable */ diff --git a/wpilibOldCommands/src/main/native/include/frc/commands/WaitCommand.h b/wpilibOldCommands/src/main/native/include/frc/commands/WaitCommand.h index 72041c5ce3..3902fb6b77 100644 --- a/wpilibOldCommands/src/main/native/include/frc/commands/WaitCommand.h +++ b/wpilibOldCommands/src/main/native/include/frc/commands/WaitCommand.h @@ -17,7 +17,6 @@ class WaitCommand : public TimedCommand { /** * Creates a new WaitCommand with the given name and timeout. * - * @param name the name of the command * @param timeout the time before this command "times out" */ explicit WaitCommand(units::second_t timeout); @@ -25,6 +24,7 @@ class WaitCommand : public TimedCommand { /** * Creates a new WaitCommand with the given timeout. * + * @param name the name of the command * @param timeout the time before this command "times out" */ WaitCommand(std::string_view name, units::second_t timeout); diff --git a/wpilibc/src/main/native/cpp/simulation/DutyCycleSim.cpp b/wpilibc/src/main/native/cpp/simulation/DutyCycleSim.cpp index 6bc2b4ca25..29f2df4b41 100644 --- a/wpilibc/src/main/native/cpp/simulation/DutyCycleSim.cpp +++ b/wpilibc/src/main/native/cpp/simulation/DutyCycleSim.cpp @@ -60,8 +60,8 @@ int DutyCycleSim::GetFrequency() const { return HALSIM_GetDutyCycleFrequency(m_index); } -void DutyCycleSim::SetFrequency(int count) { - HALSIM_SetDutyCycleFrequency(m_index, count); +void DutyCycleSim::SetFrequency(int frequency) { + HALSIM_SetDutyCycleFrequency(m_index, frequency); } std::unique_ptr DutyCycleSim::RegisterOutputCallback( @@ -77,8 +77,8 @@ double DutyCycleSim::GetOutput() const { return HALSIM_GetDutyCycleOutput(m_index); } -void DutyCycleSim::SetOutput(double period) { - HALSIM_SetDutyCycleOutput(m_index, period); +void DutyCycleSim::SetOutput(double output) { + HALSIM_SetDutyCycleOutput(m_index, output); } void DutyCycleSim::ResetData() { diff --git a/wpilibc/src/main/native/include/frc/AddressableLED.h b/wpilibc/src/main/native/include/frc/AddressableLED.h index 3f8114bcfa..561eb3756a 100644 --- a/wpilibc/src/main/native/include/frc/AddressableLED.h +++ b/wpilibc/src/main/native/include/frc/AddressableLED.h @@ -140,7 +140,7 @@ class AddressableLED { *

The sync time is the time to hold output so LEDs enable. Default set for * WS2812. * - * @param syncTimeMicroSeconds the sync time + * @param syncTime the sync time */ void SetSyncTime(units::microsecond_t syncTime); diff --git a/wpilibc/src/main/native/include/frc/AnalogGyro.h b/wpilibc/src/main/native/include/frc/AnalogGyro.h index a5a06c518e..6565c93013 100644 --- a/wpilibc/src/main/native/include/frc/AnalogGyro.h +++ b/wpilibc/src/main/native/include/frc/AnalogGyro.h @@ -48,7 +48,7 @@ class AnalogGyro : public Gyro, explicit AnalogGyro(int channel); /** - * @Gyro constructor with a precreated AnalogInput object. + * Gyro constructor with a precreated AnalogInput object. * * Use this constructor when the analog channel needs to be shared. * This object will not clean up the AnalogInput object when using this diff --git a/wpilibc/src/main/native/include/frc/AnalogInput.h b/wpilibc/src/main/native/include/frc/AnalogInput.h index 45ecb388af..ebc4e70150 100644 --- a/wpilibc/src/main/native/include/frc/AnalogInput.h +++ b/wpilibc/src/main/native/include/frc/AnalogInput.h @@ -198,8 +198,7 @@ class AnalogInput : public wpi::Sendable, * * This will be added to all values returned to the user. * - * @param initialValue The value that the accumulator should start from when - * reset. + * @param value The value that the accumulator should start from when reset. */ void SetAccumulatorInitialValue(int64_t value); diff --git a/wpilibc/src/main/native/include/frc/AnalogPotentiometer.h b/wpilibc/src/main/native/include/frc/AnalogPotentiometer.h index 29618bb6f3..3d0588dfa4 100644 --- a/wpilibc/src/main/native/include/frc/AnalogPotentiometer.h +++ b/wpilibc/src/main/native/include/frc/AnalogPotentiometer.h @@ -58,7 +58,7 @@ class AnalogPotentiometer : public wpi::Sendable, * This will calculate the result from the fullRange times the fraction of the * supply voltage, plus the offset. * - * @param channel The existing Analog Input pointer + * @param input The existing Analog Input pointer * @param fullRange The value (in desired units) representing the full * 0-5V range of the input. * @param offset The value (in desired units) representing the @@ -80,7 +80,7 @@ class AnalogPotentiometer : public wpi::Sendable, * This will calculate the result from the fullRange times the fraction of the * supply voltage, plus the offset. * - * @param channel The existing Analog Input pointer + * @param input The existing Analog Input pointer * @param fullRange The value (in desired units) representing the full * 0-5V range of the input. * @param offset The value (in desired units) representing the diff --git a/wpilibc/src/main/native/include/frc/AnalogTrigger.h b/wpilibc/src/main/native/include/frc/AnalogTrigger.h index 3d250544ac..f9c5602666 100644 --- a/wpilibc/src/main/native/include/frc/AnalogTrigger.h +++ b/wpilibc/src/main/native/include/frc/AnalogTrigger.h @@ -36,14 +36,14 @@ class AnalogTrigger : public wpi::Sendable, * This should be used in the case of sharing an analog channel between the * trigger and an analog input object. * - * @param channel The pointer to the existing AnalogInput object + * @param input The pointer to the existing AnalogInput object */ - explicit AnalogTrigger(AnalogInput* channel); + explicit AnalogTrigger(AnalogInput* input); /** * Construct an analog trigger given a duty cycle input. * - * @param channel The pointer to the existing DutyCycle object + * @param dutyCycle The pointer to the existing DutyCycle object */ explicit AnalogTrigger(DutyCycle* dutyCycle); diff --git a/wpilibc/src/main/native/include/frc/Debouncer.h b/wpilibc/src/main/native/include/frc/Debouncer.h index 53bc12744e..8f583f01db 100644 --- a/wpilibc/src/main/native/include/frc/Debouncer.h +++ b/wpilibc/src/main/native/include/frc/Debouncer.h @@ -21,10 +21,10 @@ class Debouncer { /** * Creates a new Debouncer. * - * @param debounce The number of seconds the value must change from - * baseline for the filtered value to change. - * @param type Which type of state change the debouncing will be performed - * on. + * @param debounceTime The number of seconds the value must change from + * baseline for the filtered value to change. + * @param type Which type of state change the debouncing will be + * performed on. */ explicit Debouncer(units::second_t debounceTime, DebounceType type = DebounceType::kRising); diff --git a/wpilibc/src/main/native/include/frc/DriverStation.h b/wpilibc/src/main/native/include/frc/DriverStation.h index a23c21a63e..30bf4fc372 100644 --- a/wpilibc/src/main/native/include/frc/DriverStation.h +++ b/wpilibc/src/main/native/include/frc/DriverStation.h @@ -139,6 +139,7 @@ class DriverStation { * Returns the types of Axes on a given joystick port. * * @param stick The joystick port number and the target axis + * @param axis The analog axis value to read from the joystick. * @return What type of axis the axis is reporting to be */ static int GetJoystickAxisType(int stick, int axis); diff --git a/wpilibc/src/main/native/include/frc/DutyCycleEncoder.h b/wpilibc/src/main/native/include/frc/DutyCycleEncoder.h index 50d612da29..ccf56adffd 100644 --- a/wpilibc/src/main/native/include/frc/DutyCycleEncoder.h +++ b/wpilibc/src/main/native/include/frc/DutyCycleEncoder.h @@ -58,21 +58,21 @@ class DutyCycleEncoder : public wpi::Sendable, /** * Construct a new DutyCycleEncoder attached to a DigitalSource object. * - * @param source the digital source to attach to + * @param digitalSource the digital source to attach to */ explicit DutyCycleEncoder(DigitalSource& digitalSource); /** * Construct a new DutyCycleEncoder attached to a DigitalSource object. * - * @param source the digital source to attach to + * @param digitalSource the digital source to attach to */ explicit DutyCycleEncoder(DigitalSource* digitalSource); /** * Construct a new DutyCycleEncoder attached to a DigitalSource object. * - * @param source the digital source to attach to + * @param digitalSource the digital source to attach to */ explicit DutyCycleEncoder(std::shared_ptr digitalSource); diff --git a/wpilibc/src/main/native/include/frc/Encoder.h b/wpilibc/src/main/native/include/frc/Encoder.h index 83f9e5b49c..f6753c2eac 100644 --- a/wpilibc/src/main/native/include/frc/Encoder.h +++ b/wpilibc/src/main/native/include/frc/Encoder.h @@ -325,8 +325,8 @@ class Encoder : public CounterBase, * * When this source is activated, the encoder count automatically resets. * - * @param channel A digital source to set as the encoder index - * @param type The state that will cause the encoder to reset + * @param source A digital source to set as the encoder index + * @param type The state that will cause the encoder to reset */ void SetIndexSource(const DigitalSource& source, IndexingType type = kResetOnRisingEdge); diff --git a/wpilibc/src/main/native/include/frc/Errors.h b/wpilibc/src/main/native/include/frc/Errors.h index 2562a9b82f..2caddfd494 100644 --- a/wpilibc/src/main/native/include/frc/Errors.h +++ b/wpilibc/src/main/native/include/frc/Errors.h @@ -52,12 +52,12 @@ const char* GetErrorMessage(int32_t* code); * Reports an error to the driver station (using HAL_SendError). * Generally the FRC_ReportError wrapper macro should be used instead. * - * @param status error code - * @param fileName source file name - * @param lineNumber source line number - * @param funcName source function name - * @param format error message format - * @param args error message format args + * @param[out] status error code + * @param[in] fileName source file name + * @param[in] lineNumber source line number + * @param[in] funcName source function name + * @param[in] format error message format + * @param[in] args error message format args */ void ReportErrorV(int32_t status, const char* fileName, int lineNumber, const char* funcName, fmt::string_view format, @@ -67,12 +67,12 @@ void ReportErrorV(int32_t status, const char* fileName, int lineNumber, * Reports an error to the driver station (using HAL_SendError). * Generally the FRC_ReportError wrapper macro should be used instead. * - * @param status error code - * @param fileName source file name - * @param lineNumber source line number - * @param funcName source function name - * @param format error message format - * @param args error message format args + * @param[out] status error code + * @param[in] fileName source file name + * @param[in] lineNumber source line number + * @param[in] funcName source function name + * @param[in] format error message format + * @param[in] args error message format args */ template inline void ReportError(int32_t status, const char* fileName, int lineNumber, @@ -86,11 +86,11 @@ inline void ReportError(int32_t status, const char* fileName, int lineNumber, * by the caller. Generally the FRC_MakeError wrapper macro should be used * instead. * - * @param status error code - * @param message error message details - * @param fileName source file name - * @param lineNumber source line number - * @param funcName source function name + * @param[out] status error code + * @param[in] message error message details + * @param[in] fileName source file name + * @param[in] lineNumber source line number + * @param[in] funcName source function name * @return runtime error object */ [[nodiscard]] RuntimeError MakeErrorV(int32_t status, const char* fileName, @@ -124,8 +124,8 @@ namespace warn { /** * Reports an error to the driver station (using HAL_SendError). * - * @param status error code - * @param format error message format + * @param[out] status error code + * @param[in] format error message format */ #define FRC_ReportError(status, format, ...) \ do { \ @@ -139,8 +139,8 @@ namespace warn { * Makes a runtime error exception object. This object should be thrown * by the caller. * - * @param status error code - * @param format error message format + * @param[out] status error code + * @param[in] format error message format * @return runtime error object */ #define FRC_MakeError(status, format, ...) \ @@ -151,8 +151,8 @@ namespace warn { * Checks a status code and depending on its value, either throws a * RuntimeError exception, calls ReportError, or does nothing (if no error). * - * @param status error code - * @param format error message format + * @param[out] status error code + * @param[in] format error message format */ #define FRC_CheckErrorStatus(status, format, ...) \ do { \ diff --git a/wpilibc/src/main/native/include/frc/I2C.h b/wpilibc/src/main/native/include/frc/I2C.h index 70b0f1e7c3..d874a46cdf 100644 --- a/wpilibc/src/main/native/include/frc/I2C.h +++ b/wpilibc/src/main/native/include/frc/I2C.h @@ -98,7 +98,7 @@ class I2C { * * @param registerAddress The register to read first in the transaction. * @param count The number of bytes to read in the transaction. - * @param buffer A pointer to the array of bytes to store the data + * @param data A pointer to the array of bytes to store the data * read from the device. * @return Transfer Aborted... false for success, true for aborted. */ diff --git a/wpilibc/src/main/native/include/frc/Joystick.h b/wpilibc/src/main/native/include/frc/Joystick.h index ba041df990..0d63e4e15d 100644 --- a/wpilibc/src/main/native/include/frc/Joystick.h +++ b/wpilibc/src/main/native/include/frc/Joystick.h @@ -54,7 +54,6 @@ class Joystick : public GenericHID { /** * Set the channel associated with the Y axis. * - * @param axis The axis to set the channel for. * @param channel The channel to set the axis to. */ void SetYChannel(int channel); @@ -62,7 +61,6 @@ class Joystick : public GenericHID { /** * Set the channel associated with the Z axis. * - * @param axis The axis to set the channel for. * @param channel The channel to set the axis to. */ void SetZChannel(int channel); @@ -70,7 +68,6 @@ class Joystick : public GenericHID { /** * Set the channel associated with the twist axis. * - * @param axis The axis to set the channel for. * @param channel The channel to set the axis to. */ void SetTwistChannel(int channel); @@ -78,7 +75,6 @@ class Joystick : public GenericHID { /** * Set the channel associated with the throttle axis. * - * @param axis The axis to set the channel for. * @param channel The channel to set the axis to. */ void SetThrottleChannel(int channel); diff --git a/wpilibc/src/main/native/include/frc/Preferences.h b/wpilibc/src/main/native/include/frc/Preferences.h index 026e65b5db..b939d9eeda 100644 --- a/wpilibc/src/main/native/include/frc/Preferences.h +++ b/wpilibc/src/main/native/include/frc/Preferences.h @@ -25,7 +25,7 @@ namespace frc { * * This class is thread safe. * - * This will also interact with {@link NetworkTable} by creating a table called + * This will also interact with NetworkTable by creating a table called * "Preferences" with all the key-value pairs. */ class Preferences { diff --git a/wpilibc/src/main/native/include/frc/SPI.h b/wpilibc/src/main/native/include/frc/SPI.h index 4d049a4e2c..36c82e4c73 100644 --- a/wpilibc/src/main/native/include/frc/SPI.h +++ b/wpilibc/src/main/native/include/frc/SPI.h @@ -135,10 +135,12 @@ class SPI { * If the receive FIFO is empty, there is no active transfer, and initiate * is false, errors. * - * @param initiate If true, this function pushes "0" into the transmit buffer - * and initiates a transfer. If false, this function assumes - * that data is already in the receive FIFO from a previous - * write. + * @param initiate If true, this function pushes "0" into the transmit + * buffer and initiates a transfer. If false, this + * function assumes that data is already in the receive + * FIFO from a previous write. + * @param dataReceived Buffer to receive data from the device + * @param size The length of the transaction, in bytes */ virtual int Read(bool initiate, uint8_t* dataReceived, int size); @@ -268,17 +270,17 @@ class SPI { /** * Initialize the accumulator. * - * @param period Time between reads - * @param cmd SPI command to send to request data - * @param xferSize SPI transfer size, in bytes - * @param validMask Mask to apply to received data for validity checking - * @param validData After valid_mask is applied, required matching value for - * validity checking - * @param dataShift Bit shift to apply to received data to get actual data - * value - * @param dataSize Size (in bits) of data field - * @param isSigned Is data field signed? - * @param bigEndian Is device big endian? + * @param period Time between reads + * @param cmd SPI command to send to request data + * @param xferSize SPI transfer size, in bytes + * @param validMask Mask to apply to received data for validity checking + * @param validValue After valid_mask is applied, required matching value for + * validity checking + * @param dataShift Bit shift to apply to received data to get actual data + * value + * @param dataSize Size (in bits) of data field + * @param isSigned Is data field signed? + * @param bigEndian Is device big endian? */ void InitAccumulator(units::second_t period, int cmd, int xferSize, int validMask, int validValue, int dataShift, @@ -292,17 +294,17 @@ class SPI { * --> xferSize, int validMask, int validValue, int dataShift, int dataSize, bool isSigned, bool bigEndian) * - * @param period Time between reads - * @param cmd SPI command to send to request data - * @param xferSize SPI transfer size, in bytes - * @param validMask Mask to apply to received data for validity checking - * @param validData After valid_mask is applied, required matching value for - * validity checking - * @param dataShift Bit shift to apply to received data to get actual data - * value - * @param dataSize Size (in bits) of data field - * @param isSigned Is data field signed? - * @param bigEndian Is device big endian? + * @param period Time between reads + * @param cmd SPI command to send to request data + * @param xferSize SPI transfer size, in bytes + * @param validMask Mask to apply to received data for validity checking + * @param validValue After valid_mask is applied, required matching value for + * validity checking + * @param dataShift Bit shift to apply to received data to get actual data + * value + * @param dataSize Size (in bits) of data field + * @param isSigned Is data field signed? + * @param bigEndian Is device big endian? */ WPI_DEPRECATED("Use InitAccumulator with unit-safety instead") void InitAccumulator(double period, int cmd, int xferSize, int validMask, diff --git a/wpilibc/src/main/native/include/frc/Servo.h b/wpilibc/src/main/native/include/frc/Servo.h index d1bede35e8..b1df65581c 100644 --- a/wpilibc/src/main/native/include/frc/Servo.h +++ b/wpilibc/src/main/native/include/frc/Servo.h @@ -64,7 +64,7 @@ class Servo : public PWM { * X being set and angles of more than Y degrees result in an angle of Y being * set. * - * @param degrees The angle in degrees to set the servo. + * @param angle The angle in degrees to set the servo. */ void SetAngle(double angle); diff --git a/wpilibc/src/main/native/include/frc/Solenoid.h b/wpilibc/src/main/native/include/frc/Solenoid.h index 92bd69a254..a09ffc02b3 100644 --- a/wpilibc/src/main/native/include/frc/Solenoid.h +++ b/wpilibc/src/main/native/include/frc/Solenoid.h @@ -91,8 +91,7 @@ class Solenoid : public wpi::Sendable, public wpi::SendableHelper { * the startPulse method to allow the PCM to control the timing of a pulse. * The timing can be controlled in 0.01 second increments. * - * @param durationSeconds The duration of the pulse, from 0.01 to 2.55 - * seconds. + * @param duration The duration of the pulse, from 0.01 to 2.55 seconds. * * @see startPulse() */ diff --git a/wpilibc/src/main/native/include/frc/Timer.h b/wpilibc/src/main/native/include/frc/Timer.h index 499fbe50cb..0aed658447 100644 --- a/wpilibc/src/main/native/include/frc/Timer.h +++ b/wpilibc/src/main/native/include/frc/Timer.h @@ -89,8 +89,8 @@ class Timer { /** * Check if the period specified has passed. * - * @param seconds The period to check. - * @return True if the period has passed. + * @param period The period to check. + * @return True if the period has passed. */ bool HasElapsed(units::second_t period) const; diff --git a/wpilibc/src/main/native/include/frc/drive/RobotDriveBase.h b/wpilibc/src/main/native/include/frc/drive/RobotDriveBase.h index 16f0961fc8..389d67b370 100644 --- a/wpilibc/src/main/native/include/frc/drive/RobotDriveBase.h +++ b/wpilibc/src/main/native/include/frc/drive/RobotDriveBase.h @@ -79,7 +79,7 @@ class RobotDriveBase : public MotorSafety { * @deprecated Use ApplyDeadband() in frc/MathUtil.h. */ WPI_DEPRECATED("Use ApplyDeadband() in frc/MathUtil.h") - static double ApplyDeadband(double number, double deadband); + static double ApplyDeadband(double value, double deadband); /** * Normalize all wheel speeds if the magnitude of any wheel is greater than diff --git a/wpilibc/src/main/native/include/frc/livewindow/LiveWindow.h b/wpilibc/src/main/native/include/frc/livewindow/LiveWindow.h index 66c4c6f51e..6851cde897 100644 --- a/wpilibc/src/main/native/include/frc/livewindow/LiveWindow.h +++ b/wpilibc/src/main/native/include/frc/livewindow/LiveWindow.h @@ -48,14 +48,14 @@ class LiveWindow { /** * Enable telemetry for a single component. * - * @param sendable component + * @param component sendable */ static void EnableTelemetry(wpi::Sendable* component); /** * Disable telemetry for a single component. * - * @param sendable component + * @param component sendable */ static void DisableTelemetry(wpi::Sendable* component); diff --git a/wpilibc/src/main/native/include/frc/motorcontrol/PWMMotorController.h b/wpilibc/src/main/native/include/frc/motorcontrol/PWMMotorController.h index 8b1802a577..ac6ba4b035 100644 --- a/wpilibc/src/main/native/include/frc/motorcontrol/PWMMotorController.h +++ b/wpilibc/src/main/native/include/frc/motorcontrol/PWMMotorController.h @@ -36,14 +36,14 @@ class PWMMotorController : public MotorController, * The PWM value is set using a range of -1.0 to 1.0, appropriately scaling * the value for the FPGA. * - * @param speed The speed value between -1.0 and 1.0 to set. + * @param value The speed value between -1.0 and 1.0 to set. */ void Set(double value) override; /** * Get the recently set value of the PWM. This value is affected by the * inversion property. If you want the value that is sent directly to the - * MotorController, use {@link PWM#getSpeed()} instead. + * MotorController, use PWM::GetSpeed() instead. * * @return The most recently set value for the PWM between -1.0 and 1.0. */ diff --git a/wpilibc/src/main/native/include/frc/shuffleboard/ComplexWidget.h b/wpilibc/src/main/native/include/frc/shuffleboard/ComplexWidget.h index 86e2009a74..dc49d64934 100644 --- a/wpilibc/src/main/native/include/frc/shuffleboard/ComplexWidget.h +++ b/wpilibc/src/main/native/include/frc/shuffleboard/ComplexWidget.h @@ -21,7 +21,7 @@ namespace frc { class ShuffleboardContainer; /** - * A Shuffleboard widget that handles a {@link Sendable} object such as a speed + * A Shuffleboard widget that handles a Sendable object such as a speed * controller or sensor. */ class ComplexWidget final : public ShuffleboardWidget { diff --git a/wpilibc/src/main/native/include/frc/shuffleboard/Shuffleboard.h b/wpilibc/src/main/native/include/frc/shuffleboard/Shuffleboard.h index 04c62c14d7..252d74ab2c 100644 --- a/wpilibc/src/main/native/include/frc/shuffleboard/Shuffleboard.h +++ b/wpilibc/src/main/native/include/frc/shuffleboard/Shuffleboard.h @@ -147,7 +147,7 @@ class Shuffleboard final { * Clears the custom name format for recording files. New recordings will use * the default format. * - * @see #setRecordingFileNameFormat(String) + * @see SetRecordingFileNameFormat(std::string_view) */ static void ClearRecordingFileNameFormat(); diff --git a/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardContainer.h b/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardContainer.h index f748997ad5..db58a21a58 100644 --- a/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardContainer.h +++ b/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardContainer.h @@ -57,8 +57,8 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * Gets the layout with the given type and title, creating it if it does not * already exist at the time this method is called. * - * @param title the title of the layout - * @param layoutType the type of the layout, eg "List" or "Grid" + * @param title the title of the layout + * @param type the type of the layout, eg "List" or "Grid" * @return the layout */ ShuffleboardLayout& GetLayout(std::string_view title, BuiltInLayouts type); @@ -67,8 +67,8 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * Gets the layout with the given type and title, creating it if it does not * already exist at the time this method is called. * - * @param title the title of the layout - * @param layoutType the type of the layout, eg "List" or "Grid" + * @param title the title of the layout + * @param type the type of the layout, eg "List" or "Grid" * @return the layout */ ShuffleboardLayout& GetLayout(std::string_view title, const LayoutType& type); @@ -78,13 +78,13 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * already exist at the time this method is called. Note: this method should * only be used to use a layout type that is not already built into * Shuffleboard. To use a layout built into Shuffleboard, use - * {@link #GetLayout(String, LayoutType)} and the layouts in {@link - * BuiltInLayouts}. + * GetLayout(std::string_view, const LayoutType&) and the layouts in + * BuiltInLayouts. * * @param title the title of the layout * @param type the type of the layout, eg "List Layout" or "Grid Layout" * @return the layout - * @see #GetLayout(String, LayoutType) + * @see GetLayout(std::string_view, const LayoutType&) */ ShuffleboardLayout& GetLayout(std::string_view title, std::string_view type); @@ -156,7 +156,8 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * @return a widget to display the sendable data * @throws IllegalArgumentException if a widget already exists in this * container with the given title - * @see #addPersistent(String, Object) add(String title, Object defaultValue) + * @see AddPersistent(std::string_view, std::shared_ptr) + * Add(std::string_view title, std::shared_ptr defaultValue) */ SimpleWidget& Add(std::string_view title, std::shared_ptr defaultValue); @@ -169,7 +170,8 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * @return a widget to display the sendable data * @throws IllegalArgumentException if a widget already exists in this * container with the given title - * @see #addPersistent(String, Object) add(String title, Object defaultValue) + * @see AddPersistent(std::string_view, bool) + * Add(std::string_view title, bool defaultValue) */ SimpleWidget& Add(std::string_view title, bool defaultValue); @@ -181,7 +183,8 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * @return a widget to display the sendable data * @throws IllegalArgumentException if a widget already exists in this * container with the given title - * @see #addPersistent(String, Object) add(String title, Object defaultValue) + * @see AddPersistent(std::string_view, double) + * Add(std::string_view title, double defaultValue) */ SimpleWidget& Add(std::string_view title, double defaultValue); @@ -193,7 +196,8 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * @return a widget to display the sendable data * @throws IllegalArgumentException if a widget already exists in this * container with the given title - * @see #addPersistent(String, Object) add(String title, Object defaultValue) + * @see AddPersistent(std::string_view, int) + * Add(std::string_view title, int defaultValue) */ SimpleWidget& Add(std::string_view title, int defaultValue); @@ -205,7 +209,8 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * @return a widget to display the sendable data * @throws IllegalArgumentException if a widget already exists in this * container with the given title - * @see #addPersistent(String, Object) add(String title, Object defaultValue) + * @see AddPersistent(std::string_view, std::string_view) + * Add(std::string_view title, std::string_view defaultValue) */ SimpleWidget& Add(std::string_view title, std::string_view defaultValue); @@ -217,7 +222,8 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * @return a widget to display the sendable data * @throws IllegalArgumentException if a widget already exists in this * container with the given title - * @see #addPersistent(String, Object) add(String title, Object defaultValue) + * @see AddPersistent(std::string_view, const char*) + * Add(std::string_view title, const char* defaultValue) */ SimpleWidget& Add(std::string_view title, const char* defaultValue); @@ -229,7 +235,8 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * @return a widget to display the sendable data * @throws IllegalArgumentException if a widget already exists in this * container with the given title - * @see #addPersistent(String, Object) add(String title, Object defaultValue) + * @see AddPersistent(std::string_view, wpi::span) + * Add(std::string_view title, wpi::span defaultValue) */ SimpleWidget& Add(std::string_view title, wpi::span defaultValue); @@ -241,7 +248,8 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * @return a widget to display the sendable data * @throws IllegalArgumentException if a widget already exists in this * container with the given title - * @see #addPersistent(String, Object) add(String title, Object defaultValue) + * @see AddPersistent(std::string_view, wpi::span) + * Add(std::string_view title, wpi::span defaultValue) */ SimpleWidget& Add(std::string_view title, wpi::span defaultValue); @@ -254,7 +262,8 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * @return a widget to display the sendable data * @throws IllegalArgumentException if a widget already exists in this * container with the given title - * @see #addPersistent(String, Object) add(String title, Object defaultValue) + * @see AddPersistent(std::string_view, wpi::span) + * Add(std::string_view title, wpi::span defaultValue) */ SimpleWidget& Add(std::string_view title, wpi::span defaultValue); @@ -266,7 +275,7 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * supplier. * * @param title the title of the widget - * @param valueSupplier the supplier for values + * @param supplier the supplier for values * @return a widget to display data */ SuppliedValueWidget& AddString( @@ -279,7 +288,7 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * supplier. * * @param title the title of the widget - * @param valueSupplier the supplier for values + * @param supplier the supplier for values * @return a widget to display data */ SuppliedValueWidget& AddNumber(std::string_view title, @@ -292,7 +301,7 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * supplier. * * @param title the title of the widget - * @param valueSupplier the supplier for values + * @param supplier the supplier for values * @return a widget to display data */ SuppliedValueWidget& AddBoolean(std::string_view title, @@ -305,7 +314,7 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * supplier. * * @param title the title of the widget - * @param valueSupplier the supplier for values + * @param supplier the supplier for values * @return a widget to display data */ SuppliedValueWidget>& AddStringArray( @@ -319,7 +328,7 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * supplier. * * @param title the title of the widget - * @param valueSupplier the supplier for values + * @param supplier the supplier for values * @return a widget to display data */ SuppliedValueWidget>& AddNumberArray( @@ -332,7 +341,7 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * supplier. * * @param title the title of the widget - * @param valueSupplier the supplier for values + * @param supplier the supplier for values * @return a widget to display data */ SuppliedValueWidget>& AddBooleanArray( @@ -345,7 +354,7 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { * supplier. * * @param title the title of the widget - * @param valueSupplier the supplier for values + * @param supplier the supplier for values * @return a widget to display data */ SuppliedValueWidget& AddRaw( @@ -354,14 +363,15 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { /** * Adds a widget to this container to display a simple piece of data. * - * Unlike {@link #add(String, Object)}, the value in the widget will be saved - * on the robot and will be used when the robot program next starts rather - * than {@code defaultValue}. + * Unlike Add(std::string_view, std::shared_ptr), the value in the + * widget will be saved on the robot and will be used when the robot program + * next starts rather than {@code defaultValue}. * * @param title the title of the widget * @param defaultValue the default value of the widget * @return a widget to display the sendable data - * @see #add(String, Object) add(String title, Object defaultValue) + * @see Add(stdd::string_view, std::shared_ptr) + * Add(std::string_view title, std::shared_ptr defaultValue) */ SimpleWidget& AddPersistent(std::string_view title, std::shared_ptr defaultValue); @@ -369,56 +379,60 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { /** * Adds a widget to this container to display a simple piece of data. * - * Unlike {@link #add(String, Object)}, the value in the widget will be saved + * Unlike Add(std::string_view, bool), the value in the widget will be saved * on the robot and will be used when the robot program next starts rather * than {@code defaultValue}. * * @param title the title of the widget * @param defaultValue the default value of the widget * @return a widget to display the sendable data - * @see #add(String, Object) add(String title, Object defaultValue) + * @see Add(std::string_view, bool) + * Add(std::string_view title, bool defaultValue) */ SimpleWidget& AddPersistent(std::string_view title, bool defaultValue); /** * Adds a widget to this container to display a simple piece of data. * - * Unlike {@link #add(String, Object)}, the value in the widget will be saved + * Unlike Add(std::string_view, double), the value in the widget will be saved * on the robot and will be used when the robot program next starts rather * than {@code defaultValue}. * * @param title the title of the widget * @param defaultValue the default value of the widget * @return a widget to display the sendable data - * @see #add(String, Object) add(String title, Object defaultValue) + * @see Add(std::string_view, double) + * Add(std::string_view title, double defaultValue) */ SimpleWidget& AddPersistent(std::string_view title, double defaultValue); /** * Adds a widget to this container to display a simple piece of data. * - * Unlike {@link #add(String, Object)}, the value in the widget will be saved - * on the robot and will be used when the robot program next starts rather - * than {@code defaultValue}. + * Unlike Add(std::string_view, int), the value in the widget will be saved on + * the robot and will be used when the robot program next starts rather than + * {@code defaultValue}. * * @param title the title of the widget * @param defaultValue the default value of the widget * @return a widget to display the sendable data - * @see #add(String, Object) add(String title, Object defaultValue) + * @see Add(std:string_view, int) + * Add(std::string_view title, int defaultValue) */ SimpleWidget& AddPersistent(std::string_view title, int defaultValue); /** * Adds a widget to this container to display a simple piece of data. * - * Unlike {@link #add(String, Object)}, the value in the widget will be saved - * on the robot and will be used when the robot program next starts rather - * than {@code defaultValue}. + * Unlike Add(std::string_view, std::string_view), the value in the widget + * will be saved on the robot and will be used when the robot program next + * starts rather than {@code defaultValue}. * * @param title the title of the widget * @param defaultValue the default value of the widget * @return a widget to display the sendable data - * @see #add(String, Object) add(String title, Object defaultValue) + * @see Add(std::string_view, std::string_view) + * Add(std::string_view title, std::string_view defaultValue) */ SimpleWidget& AddPersistent(std::string_view title, std::string_view defaultValue); @@ -426,14 +440,15 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { /** * Adds a widget to this container to display a simple piece of data. * - * Unlike {@link #add(String, Object)}, the value in the widget will be saved - * on the robot and will be used when the robot program next starts rather - * than {@code defaultValue}. + * Unlike Add(std::string_view, wpi::span), the value in the + * widget will be saved on the robot and will be used when the robot program + * next starts rather than {@code defaultValue}. * * @param title the title of the widget * @param defaultValue the default value of the widget * @return a widget to display the sendable data - * @see #add(String, Object) add(String title, Object defaultValue) + * @see Add(std::string_view, wpi::span) + * Add(std::string_view title, wpi::span defaultValue) */ SimpleWidget& AddPersistent(std::string_view title, wpi::span defaultValue); @@ -441,14 +456,15 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { /** * Adds a widget to this container to display a simple piece of data. * - * Unlike {@link #add(String, Object)}, the value in the widget will be saved - * on the robot and will be used when the robot program next starts rather - * than {@code defaultValue}. + * Unlike Add(std::string_view, wpi::span), the value in the + * widget will be saved on the robot and will be used when the robot program + * next starts rather than {@code defaultValue}. * * @param title the title of the widget * @param defaultValue the default value of the widget * @return a widget to display the sendable data - * @see #add(String, Object) add(String title, Object defaultValue) + * @see Add(std::string_view, wpi::span) + * Add(std::string_view title, wpi::span defaultValue) */ SimpleWidget& AddPersistent(std::string_view title, wpi::span defaultValue); @@ -456,14 +472,15 @@ class ShuffleboardContainer : public virtual ShuffleboardValue { /** * Adds a widget to this container to display a simple piece of data. * - * Unlike {@link #add(String, Object)}, the value in the widget will be saved - * on the robot and will be used when the robot program next starts rather - * than {@code defaultValue}. + * Unlike Add(std::string_view, wpi::span), the value in + * the widget will be saved on the robot and will be used when the robot + * program next starts rather than {@code defaultValue}. * * @param title the title of the widget * @param defaultValue the default value of the widget * @return a widget to display the sendable data - * @see #add(String, Object) add(String title, Object defaultValue) + * @see Add(std::string_view, wpi::span) + * Add(std::string_view title, wpi::span defaultValue) */ SimpleWidget& AddPersistent(std::string_view title, wpi::span defaultValue); diff --git a/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardTab.h b/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardTab.h index 1dd1aac311..8864cdb97d 100644 --- a/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardTab.h +++ b/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardTab.h @@ -17,10 +17,11 @@ class ShuffleboardRoot; /** * Represents a tab in the Shuffleboard dashboard. Widgets can be added to the - * tab with {@link #add(Sendable)}, {@link #add(String, Object)}, and - * {@link #add(String, Sendable)}. Widgets can also be added to layouts with - * {@link #getLayout(String, String)}; layouts can be nested arbitrarily deep - * (note that too many levels may make deeper components unusable). + * tab with Add(Sendable), Add(std::string_view, Object), and + * Add(String, Sendable). Widgets can also be added to layouts with + * GetLayout(std::string_view, std::string_view); layouts can be nested + * arbitrarily deep (note that too many levels may make deeper components + * unusable). */ class ShuffleboardTab final : public ShuffleboardContainer { public: diff --git a/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardValue.h b/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardValue.h index c2053cd7c9..4b7ccd46e7 100644 --- a/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardValue.h +++ b/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardValue.h @@ -47,7 +47,7 @@ class ShuffleboardValue { * * This method is package-private to prevent users from enabling control * themselves. Has no effect if the sendable is not marked as an actuator with - * {@link SendableBuilder#setActuator}. + * SendableBuilder::SetActuator(). */ virtual void EnableIfActuator() {} @@ -56,7 +56,7 @@ class ShuffleboardValue { * * This method is package-private to prevent users from enabling control * themselves. Has no effect if the sendable is not marked as an actuator with - * {@link SendableBuilder#setActuator}. + * SendableBuilder::SetActuator(). */ virtual void DisableIfActuator() {} diff --git a/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardWidget.h b/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardWidget.h index 6134fa3c7d..ce01367074 100644 --- a/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardWidget.h +++ b/wpilibc/src/main/native/include/frc/shuffleboard/ShuffleboardWidget.h @@ -60,8 +60,7 @@ class ShuffleboardWidget : public ShuffleboardComponent { * widget type will be used. This method should only be used to use a widget * that does not come built into Shuffleboard (i.e. one that comes with a * custom or third-party plugin). To use a widget that is built into - * Shuffleboard, use {@link #withWidget(WidgetType)} and {@link - * BuiltInWidgets}. + * Shuffleboard, use WithWidget(WidgetType) and BuiltInWidgets. * * @param widgetType the type of the widget used to display the data * @return this widget object diff --git a/wpilibc/src/main/native/include/frc/simulation/ADXL345Sim.h b/wpilibc/src/main/native/include/frc/simulation/ADXL345Sim.h index ab0c1c7709..af96b39e74 100644 --- a/wpilibc/src/main/native/include/frc/simulation/ADXL345Sim.h +++ b/wpilibc/src/main/native/include/frc/simulation/ADXL345Sim.h @@ -21,29 +21,35 @@ class ADXL345Sim { /** * Constructs from a ADXL345_I2C object. * - * @param ADXL345 accel to simulate + * @param accel ADXL345 accel to simulate */ explicit ADXL345Sim(const ADXL345_I2C& accel); /** * Constructs from a ADXL345_SPI object. * - * @param ADXL345 accel to simulate + * @param accel ADXL345 accel to simulate */ explicit ADXL345Sim(const ADXL345_SPI& accel); /** * Sets the X acceleration. + * + * @param accel The X acceleration. */ void SetX(double accel); /** * Sets the Y acceleration. + * + * @param accel The Y acceleration. */ void SetY(double accel); /** * Sets the Z acceleration. + * + * @param accel The Z acceleration. */ void SetZ(double accel); diff --git a/wpilibc/src/main/native/include/frc/simulation/ADXL362Sim.h b/wpilibc/src/main/native/include/frc/simulation/ADXL362Sim.h index 27882b75ff..269732b3bf 100644 --- a/wpilibc/src/main/native/include/frc/simulation/ADXL362Sim.h +++ b/wpilibc/src/main/native/include/frc/simulation/ADXL362Sim.h @@ -20,22 +20,28 @@ class ADXL362Sim { /** * Constructs from a ADXL362 object. * - * @param ADXL362 accel to simulate + * @param accel ADXL362 accel to simulate */ explicit ADXL362Sim(const ADXL362& accel); /** * Sets the X acceleration. + * + * @param accel The X acceleration. */ void SetX(double accel); /** * Sets the Y acceleration. + * + * @param accel The Y acceleration. */ void SetY(double accel); /** * Sets the Z acceleration. + * + * @param accel The Z acceleration. */ void SetZ(double accel); diff --git a/wpilibc/src/main/native/include/frc/simulation/AddressableLEDSim.h b/wpilibc/src/main/native/include/frc/simulation/AddressableLEDSim.h index 1d8db85d21..4533086156 100644 --- a/wpilibc/src/main/native/include/frc/simulation/AddressableLEDSim.h +++ b/wpilibc/src/main/native/include/frc/simulation/AddressableLEDSim.h @@ -157,6 +157,7 @@ class AddressableLEDSim { * * @param callback the callback that will be called whenever the LED data is * changed + * @param initialNotify if true, the callback will be run on the initial value * @return the CallbackStore object associated with this callback */ [[nodiscard]] std::unique_ptr RegisterDataCallback( diff --git a/wpilibc/src/main/native/include/frc/simulation/BatterySim.h b/wpilibc/src/main/native/include/frc/simulation/BatterySim.h index 115635e22d..4a350cfd01 100644 --- a/wpilibc/src/main/native/include/frc/simulation/BatterySim.h +++ b/wpilibc/src/main/native/include/frc/simulation/BatterySim.h @@ -19,9 +19,9 @@ class BatterySim { public: /** * Calculate the loaded battery voltage. Use this with - * {@link RoboRioSim#setVInVoltage(double)} to set the simulated battery - * voltage, which can then be retrieved with the {@link - * RobotController#getBatteryVoltage()} method. + * RoboRioSim::SetVInVoltage(double) to set the simulated battery voltage, + * which can then be retrieved with the RobotController::GetBatteryVoltage() + * method. * * @param nominalVoltage The nominal battery voltage. Usually 12v. * @param resistance The forward resistance of the battery. Most batteries @@ -38,10 +38,10 @@ class BatterySim { /** * Calculate the loaded battery voltage. Use this with - * {@link RoboRioSim#setVInVoltage(double)} to set the simulated battery - * voltage, which can then be retrieved with the {@link - * RobotController#getBatteryVoltage()} method. This function assumes a - * nominal voltage of 12v and a resistance of 20 milliohms (0.020 ohms) + * RoboRioSimSetVInVoltage(double) to set the simulated battery voltage, which + * can then be retrieved with the RobotController::GetBatteryVoltage() method. + * This function assumes a nominal voltage of 12V and a resistance of 20 + * milliohms (0.020 ohms). * * @param currents The currents drawn from the battery. * @return The battery's voltage under load. diff --git a/wpilibc/src/main/native/include/frc/simulation/CTREPCMSim.h b/wpilibc/src/main/native/include/frc/simulation/CTREPCMSim.h index 43d2ad6a22..0929308d86 100644 --- a/wpilibc/src/main/native/include/frc/simulation/CTREPCMSim.h +++ b/wpilibc/src/main/native/include/frc/simulation/CTREPCMSim.h @@ -37,7 +37,6 @@ class CTREPCMSim { /** * Register a callback to be run when a solenoid is initialized on a channel. * - * @param channel the channel to monitor * @param callback the callback * @param initialNotify should the callback be run with the initial state * @return the CallbackStore object associated with this callback @@ -55,7 +54,6 @@ class CTREPCMSim { /** * Define whether a solenoid has been initialized on a specific channel. * - * @param channel the channel * @param solenoidInitialized is there a solenoid initialized on that channel */ void SetInitialized(bool solenoidInitialized); diff --git a/wpilibc/src/main/native/include/frc/simulation/DifferentialDrivetrainSim.h b/wpilibc/src/main/native/include/frc/simulation/DifferentialDrivetrainSim.h index 3de59b5aea..959e2c970e 100644 --- a/wpilibc/src/main/native/include/frc/simulation/DifferentialDrivetrainSim.h +++ b/wpilibc/src/main/native/include/frc/simulation/DifferentialDrivetrainSim.h @@ -21,24 +21,24 @@ class DifferentialDrivetrainSim { /** * Create a SimDrivetrain. * - * @param drivetrainPlant The LinearSystem representing the robot's - * drivetrain. This system can be created with - * LinearSystemId#createDrivetrainVelocitySystem or - * LinearSystemId#identifyDrivetrainSystem. - * @param trackWidth The robot's track width. - * @param driveMotor A {@link DCMotor} representing the left side of - * the drivetrain. - * @param gearingRatio The gearingRatio ratio of the left side, as output - * over input. This must be the same ratio as the ratio used to identify or - * create the drivetrainPlant. - * @param wheelRadiusMeters The radius of the wheels on the drivetrain, in - * meters. + * @param plant The LinearSystem representing the robot's drivetrain. This + * system can be created with + * LinearSystemId::DrivetrainVelocitySystem() or + * LinearSystemId::IdentifyDrivetrainSystem(). + * @param trackWidth The robot's track width. + * @param driveMotor A DCMotor representing the left side of the drivetrain. + * @param gearingRatio The gearingRatio ratio of the left side, as output over + * input. This must be the same ratio as the ratio used to + * identify or create the plant. + * @param wheelRadius The radius of the wheels on the drivetrain, in meters. * @param measurementStdDevs Standard deviations for measurements, in the form - * [x, y, heading, left velocity, right velocity, left distance, right - * distance]ᵀ. Can be omitted if no noise is desired. Gyro standard - * deviations of 0.0001 radians, velocity standard deviations of 0.05 m/s, and - * position measurement standard deviations of 0.005 meters are a reasonable - * starting point. + * [x, y, heading, left velocity, right velocity, + * left distance, right distance]ᵀ. Can be omitted + * if no noise is desired. Gyro standard deviations + * of 0.0001 radians, velocity standard deviations + * of 0.05 m/s, and position measurement standard + * deviations of 0.005 meters are a reasonable + * starting point. */ DifferentialDrivetrainSim( LinearSystem<2, 2, 2> plant, units::meter_t trackWidth, @@ -48,23 +48,24 @@ class DifferentialDrivetrainSim { /** * Create a SimDrivetrain. * - * @param driveMotor A {@link DCMotor} representing the left side of the - * drivetrain. + * @param driveMotor A DCMotor representing the left side of the drivetrain. * @param gearing The gearing on the drive between motor and wheel, as - * output over input. This must be the same ratio as the ratio used to - * identify or create the drivetrainPlant. + * output over input. This must be the same ratio as the + * ratio used to identify or create the plant. * @param J The moment of inertia of the drivetrain about its - * center. + * center. * @param mass The mass of the drivebase. * @param wheelRadius The radius of the wheels on the drivetrain. * @param trackWidth The robot's track width, or distance between left and - * right wheels. + * right wheels. * @param measurementStdDevs Standard deviations for measurements, in the form - * [x, y, heading, left velocity, right velocity, left distance, right - * distance]ᵀ. Can be omitted if no noise is desired. Gyro standard - * deviations of 0.0001 radians, velocity standard deviations of 0.05 m/s, and - * position measurement standard deviations of 0.005 meters are a reasonable - * starting point. + * [x, y, heading, left velocity, right velocity, + * left distance, right distance]ᵀ. Can be omitted + * if no noise is desired. Gyro standard deviations + * of 0.0001 radians, velocity standard deviations + * of 0.05 m/s, and position measurement standard + * deviations of 0.005 meters are a reasonable + * starting point. */ DifferentialDrivetrainSim( frc::DCMotor driveMotor, double gearing, units::kilogram_square_meter_t J, @@ -73,11 +74,10 @@ class DifferentialDrivetrainSim { const std::array& measurementStdDevs = {}); /** - * Clamp the input vector such that no element exceeds the given voltage. If - * any does, the relative magnitudes of the input will be maintained. + * Clamp the input vector such that no element exceeds the battery voltage. + * If any does, the relative magnitudes of the input will be maintained. * - * @param u The input vector. - * @param maxVoltage The maximum voltage. + * @param u The input vector. * @return The normalized input. */ Eigen::Vector ClampInput(const Eigen::Vector& u); @@ -102,8 +102,8 @@ class DifferentialDrivetrainSim { /** * Updates the simulation. * - * @param dt The time that's passed since the last {@link #update(double)} - * call. + * @param dt The time that's passed since the last Update(units::second_t) + * call. */ void Update(units::second_t dt); diff --git a/wpilibc/src/main/native/include/frc/simulation/DutyCycleEncoderSim.h b/wpilibc/src/main/native/include/frc/simulation/DutyCycleEncoderSim.h index 4994393fe2..19577bb801 100644 --- a/wpilibc/src/main/native/include/frc/simulation/DutyCycleEncoderSim.h +++ b/wpilibc/src/main/native/include/frc/simulation/DutyCycleEncoderSim.h @@ -21,7 +21,7 @@ class DutyCycleEncoderSim { /** * Constructs from a DutyCycleEncoder object. * - * @param dutyCycleEncoder DutyCycleEncoder to simulate + * @param encoder DutyCycleEncoder to simulate */ explicit DutyCycleEncoderSim(const DutyCycleEncoder& encoder); diff --git a/wpilibc/src/main/native/include/frc/simulation/DutyCycleSim.h b/wpilibc/src/main/native/include/frc/simulation/DutyCycleSim.h index 93fa0a79bf..ec7b48c8b4 100644 --- a/wpilibc/src/main/native/include/frc/simulation/DutyCycleSim.h +++ b/wpilibc/src/main/native/include/frc/simulation/DutyCycleSim.h @@ -90,7 +90,7 @@ class DutyCycleSim { * * @param frequency the new frequency */ - void SetFrequency(int count); + void SetFrequency(int frequency); /** * Register a callback to be run whenever the output changes. @@ -114,7 +114,7 @@ class DutyCycleSim { * * @param output the new output value */ - void SetOutput(double period); + void SetOutput(double output); /** * Reset all simulation data for the duty cycle output. diff --git a/wpilibc/src/main/native/include/frc/simulation/PowerDistributionSim.h b/wpilibc/src/main/native/include/frc/simulation/PowerDistributionSim.h index 34891c5f8d..ac54da2f0a 100644 --- a/wpilibc/src/main/native/include/frc/simulation/PowerDistributionSim.h +++ b/wpilibc/src/main/native/include/frc/simulation/PowerDistributionSim.h @@ -140,7 +140,8 @@ class PowerDistributionSim { * * @param currents output array; set to the current in each channel. The * array must be big enough to hold all the PowerDistribution - * channels + * channels + * @param length length of output array */ void GetAllCurrents(double* currents, int length) const; @@ -149,7 +150,8 @@ class PowerDistributionSim { * * @param currents array containing the current values for each channel. The * array must be big enough to hold all the PowerDistribution - * channels + * channels + * @param length length of array */ void SetAllCurrents(const double* currents, int length); diff --git a/wpilibc/src/main/native/include/frc/simulation/REVPHSim.h b/wpilibc/src/main/native/include/frc/simulation/REVPHSim.h index 0097d6f2cb..97e31bfbbe 100644 --- a/wpilibc/src/main/native/include/frc/simulation/REVPHSim.h +++ b/wpilibc/src/main/native/include/frc/simulation/REVPHSim.h @@ -37,7 +37,6 @@ class REVPHSim { /** * Register a callback to be run when a solenoid is initialized on a channel. * - * @param channel the channel to monitor * @param callback the callback * @param initialNotify should the callback be run with the initial state * @return the CallbackStore object associated with this callback @@ -55,7 +54,6 @@ class REVPHSim { /** * Define whether a solenoid has been initialized on a specific channel. * - * @param channel the channel * @param solenoidInitialized is there a solenoid initialized on that channel */ void SetInitialized(bool solenoidInitialized); diff --git a/wpilibc/src/main/native/include/frc/simulation/RoboRioSim.h b/wpilibc/src/main/native/include/frc/simulation/RoboRioSim.h index 6475073717..10951061fc 100644 --- a/wpilibc/src/main/native/include/frc/simulation/RoboRioSim.h +++ b/wpilibc/src/main/native/include/frc/simulation/RoboRioSim.h @@ -38,7 +38,7 @@ class RoboRioSim { /** * Define the state of the FPGA button. * - * @param fpgaButton the new state + * @param fPGAButton the new state */ static void SetFPGAButton(bool fPGAButton); @@ -414,7 +414,7 @@ class RoboRioSim { /** * Define the brownout voltage. * - * @param vInVoltage the new voltage + * @param brownoutVoltage the new voltage */ static void SetBrownoutVoltage(units::volt_t brownoutVoltage); diff --git a/wpilibc/src/main/native/include/frc/simulation/UltrasonicSim.h b/wpilibc/src/main/native/include/frc/simulation/UltrasonicSim.h index f95cf0dd68..efa9b3700b 100644 --- a/wpilibc/src/main/native/include/frc/simulation/UltrasonicSim.h +++ b/wpilibc/src/main/native/include/frc/simulation/UltrasonicSim.h @@ -28,14 +28,14 @@ class UltrasonicSim { /** * Sets if the range measurement is valid. * - * @param valid True if valid + * @param isValid True if valid */ void SetRangeValid(bool isValid); /** * Sets the range measurement * - * @param rate The range + * @param range The range */ void SetRange(units::meter_t range); diff --git a/wpilibc/src/main/native/include/frc/smartdashboard/FieldObject2d.h b/wpilibc/src/main/native/include/frc/smartdashboard/FieldObject2d.h index 29cec86d7c..2e41d843a0 100644 --- a/wpilibc/src/main/native/include/frc/smartdashboard/FieldObject2d.h +++ b/wpilibc/src/main/native/include/frc/smartdashboard/FieldObject2d.h @@ -72,7 +72,6 @@ class FieldObject2d { * Set multiple poses from an array of Pose objects. * The total number of poses is limited to 85. * - * @param obj Object entry * @param poses array of 2D poses */ void SetPoses(std::initializer_list poses); @@ -95,7 +94,6 @@ class FieldObject2d { /** * Get multiple poses. * - * @param obj Object entry * @param out output SmallVector to hold 2D poses * @return span referring to output SmallVector */ diff --git a/wpilibc/src/main/native/include/frc/smartdashboard/Mechanism2d.h b/wpilibc/src/main/native/include/frc/smartdashboard/Mechanism2d.h index c1d3767e95..cbe25bef83 100644 --- a/wpilibc/src/main/native/include/frc/smartdashboard/Mechanism2d.h +++ b/wpilibc/src/main/native/include/frc/smartdashboard/Mechanism2d.h @@ -48,6 +48,7 @@ class Mechanism2d : public nt::NTSendable, * * @param width the width * @param height the height + * @param backgroundColor the background color */ Mechanism2d(double width, double height, const Color8Bit& backgroundColor = {0, 0, 32}); diff --git a/wpilibc/src/main/native/include/frc/smartdashboard/MechanismLigament2d.h b/wpilibc/src/main/native/include/frc/smartdashboard/MechanismLigament2d.h index aa208cb2bf..70abaa6db3 100644 --- a/wpilibc/src/main/native/include/frc/smartdashboard/MechanismLigament2d.h +++ b/wpilibc/src/main/native/include/frc/smartdashboard/MechanismLigament2d.h @@ -53,7 +53,7 @@ class MechanismLigament2d : public MechanismObject2d { /** * Set the ligament's angle relative to its parent. * - * @param degrees the angle + * @param angle the angle */ void SetAngle(units::degree_t angle); @@ -67,7 +67,7 @@ class MechanismLigament2d : public MechanismObject2d { /** * Set the line thickness. * - * @param weight the line thickness + * @param lineWidth the line thickness */ void SetLineWeight(double lineWidth); diff --git a/wpilibc/src/main/native/include/frc/smartdashboard/SmartDashboard.h b/wpilibc/src/main/native/include/frc/smartdashboard/SmartDashboard.h index d08833c3b6..47c4a28e76 100644 --- a/wpilibc/src/main/native/include/frc/smartdashboard/SmartDashboard.h +++ b/wpilibc/src/main/native/include/frc/smartdashboard/SmartDashboard.h @@ -114,8 +114,8 @@ class SmartDashboard { * In order for the value to appear in the dashboard, it must be registered * with SendableRegistry. WPILib components do this automatically. * - * @param keyName the key - * @param value the value + * @param key the key + * @param data the value */ static void PutData(std::string_view key, wpi::Sendable* data); @@ -167,6 +167,7 @@ class SmartDashboard { * If the key is not found, returns the default value. * * @param keyName the key + * @param defaultValue the default value to set if key doesn't exist * @return the value */ static bool GetBoolean(std::string_view keyName, bool defaultValue); @@ -198,6 +199,7 @@ class SmartDashboard { * If the key is not found, returns the default value. * * @param keyName the key + * @param defaultValue the default value to set if the key doesn't exist * @return the value */ static double GetNumber(std::string_view keyName, double defaultValue); @@ -230,6 +232,7 @@ class SmartDashboard { * If the key is not found, returns the default value. * * @param keyName the key + * @param defaultValue the default value to set if the key doesn't exist * @return the value */ static std::string GetString(std::string_view keyName, @@ -418,7 +421,6 @@ class SmartDashboard { * complex data object. * * @param keyName the key - * @param value the object to retrieve the value into */ static std::shared_ptr GetValue(std::string_view keyName); diff --git a/wpilibc/src/main/native/include/frc/util/Color.h b/wpilibc/src/main/native/include/frc/util/Color.h index 4c8f56d9a8..00bc4afa18 100644 --- a/wpilibc/src/main/native/include/frc/util/Color.h +++ b/wpilibc/src/main/native/include/frc/util/Color.h @@ -743,9 +743,9 @@ class Color { /** * Constructs a Color. * - * @param red Red value (0-1) - * @param green Green value (0-1) - * @param blue Blue value (0-1) + * @param r Red value (0-1) + * @param g Green value (0-1) + * @param b Blue value (0-1) */ constexpr Color(double r, double g, double b) : red(roundAndClamp(r)), diff --git a/wpilibc/src/main/native/include/frc/util/Color8Bit.h b/wpilibc/src/main/native/include/frc/util/Color8Bit.h index f289865031..62cbde97ce 100644 --- a/wpilibc/src/main/native/include/frc/util/Color8Bit.h +++ b/wpilibc/src/main/native/include/frc/util/Color8Bit.h @@ -20,9 +20,9 @@ class Color8Bit { /** * Constructs a Color8Bit. * - * @param red Red value (0-255) - * @param green Green value (0-255) - * @param blue Blue value (0-255) + * @param r Red value (0-255) + * @param g Green value (0-255) + * @param b Blue value (0-255) */ constexpr Color8Bit(int r, int g, int b) : red(std::clamp(r, 0, 255)), diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/simulation/DifferentialDrivetrainSim.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/simulation/DifferentialDrivetrainSim.java index 3401a75e36..483dee85a5 100644 --- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/simulation/DifferentialDrivetrainSim.java +++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/simulation/DifferentialDrivetrainSim.java @@ -353,7 +353,7 @@ public class DifferentialDrivetrainSim { } /** - * Clamp the input vector such that no element exceeds the given voltage. If any does, the + * Clamp the input vector such that no element exceeds the battery voltage. If any does, the * relative magnitudes of the input will be maintained. * * @param u The input vector. diff --git a/wpimath/src/main/native/cpp/trajectory/TrajectoryUtil.cpp b/wpimath/src/main/native/cpp/trajectory/TrajectoryUtil.cpp index 29e27ec430..169b642a6c 100644 --- a/wpimath/src/main/native/cpp/trajectory/TrajectoryUtil.cpp +++ b/wpimath/src/main/native/cpp/trajectory/TrajectoryUtil.cpp @@ -47,7 +47,7 @@ std::string TrajectoryUtil::SerializeTrajectory(const Trajectory& trajectory) { return json.dump(); } -Trajectory TrajectoryUtil::DeserializeTrajectory(std::string_view json_str) { - wpi::json json = wpi::json::parse(json_str); +Trajectory TrajectoryUtil::DeserializeTrajectory(std::string_view jsonStr) { + wpi::json json = wpi::json::parse(jsonStr); return Trajectory{json.get>()}; } diff --git a/wpimath/src/main/native/include/frc/controller/ControlAffinePlantInversionFeedforward.h b/wpimath/src/main/native/include/frc/controller/ControlAffinePlantInversionFeedforward.h index 1d60b86789..8646084c45 100644 --- a/wpimath/src/main/native/include/frc/controller/ControlAffinePlantInversionFeedforward.h +++ b/wpimath/src/main/native/include/frc/controller/ControlAffinePlantInversionFeedforward.h @@ -97,7 +97,7 @@ class ControlAffinePlantInversionFeedforward { /** * Returns an element of the previously calculated feedforward. * - * @param row Row of uff. + * @param i Row of uff. * * @return The row of the calculated feedforward. */ diff --git a/wpimath/src/main/native/include/frc/controller/HolonomicDriveController.h b/wpimath/src/main/native/include/frc/controller/HolonomicDriveController.h index fe8529dd4d..398a872bad 100644 --- a/wpimath/src/main/native/include/frc/controller/HolonomicDriveController.h +++ b/wpimath/src/main/native/include/frc/controller/HolonomicDriveController.h @@ -54,7 +54,7 @@ class WPILIB_DLLEXPORT HolonomicDriveController { * Sets the pose error which is considered tolerable for use with * AtReference(). * - * @param poseTolerance Pose error which is tolerable. + * @param tolerance Pose error which is tolerable. */ void SetTolerance(const Pose2d& tolerance); diff --git a/wpimath/src/main/native/include/frc/controller/LinearPlantInversionFeedforward.h b/wpimath/src/main/native/include/frc/controller/LinearPlantInversionFeedforward.h index cb4f907d1b..454ccb098a 100644 --- a/wpimath/src/main/native/include/frc/controller/LinearPlantInversionFeedforward.h +++ b/wpimath/src/main/native/include/frc/controller/LinearPlantInversionFeedforward.h @@ -31,8 +31,8 @@ class LinearPlantInversionFeedforward { /** * Constructs a feedforward with the given plant. * - * @param plant The plant being controlled. - * @param dtSeconds Discretization timestep. + * @param plant The plant being controlled. + * @param dt Discretization timestep. */ template LinearPlantInversionFeedforward( @@ -42,9 +42,9 @@ class LinearPlantInversionFeedforward { /** * Constructs a feedforward with the given coefficients. * - * @param A Continuous system matrix of the plant being controlled. - * @param B Continuous input matrix of the plant being controlled. - * @param dtSeconds Discretization timestep. + * @param A Continuous system matrix of the plant being controlled. + * @param B Continuous input matrix of the plant being controlled. + * @param dt Discretization timestep. */ LinearPlantInversionFeedforward( const Eigen::Matrix& A, @@ -64,7 +64,7 @@ class LinearPlantInversionFeedforward { /** * Returns an element of the previously calculated feedforward. * - * @param row Row of uff. + * @param i Row of uff. * * @return The row of the calculated feedforward. */ diff --git a/wpimath/src/main/native/include/frc/controller/PIDController.h b/wpimath/src/main/native/include/frc/controller/PIDController.h index 2dfb9e520a..98625f8c14 100644 --- a/wpimath/src/main/native/include/frc/controller/PIDController.h +++ b/wpimath/src/main/native/include/frc/controller/PIDController.h @@ -159,7 +159,7 @@ class WPILIB_DLLEXPORT PIDController * Sets the error which is considered tolerable for use with AtSetpoint(). * * @param positionTolerance Position error which is tolerable. - * @param velociytTolerance Velocity error which is tolerable. + * @param velocityTolerance Velocity error which is tolerable. */ void SetTolerance( double positionTolerance, diff --git a/wpimath/src/main/native/include/frc/estimator/DifferentialDrivePoseEstimator.h b/wpimath/src/main/native/include/frc/estimator/DifferentialDrivePoseEstimator.h index 4c875b0803..698c623833 100644 --- a/wpimath/src/main/native/include/frc/estimator/DifferentialDrivePoseEstimator.h +++ b/wpimath/src/main/native/include/frc/estimator/DifferentialDrivePoseEstimator.h @@ -179,6 +179,7 @@ class WPILIB_DLLEXPORT DifferentialDrivePoseEstimator { * Note that this should be called every loop iteration. * * @param gyroAngle The current gyro angle. + * @param wheelSpeeds The velocities of the wheels in meters per second. * @param leftDistance The distance traveled by the left encoder. * @param rightDistance The distance traveled by the right encoder. * @@ -194,6 +195,7 @@ class WPILIB_DLLEXPORT DifferentialDrivePoseEstimator { * * @param currentTime The time at which this method was called. * @param gyroAngle The current gyro angle. + * @param wheelSpeeds The velocities of the wheels in meters per second. * @param leftDistance The distance traveled by the left encoder. * @param rightDistance The distance traveled by the right encoder. * diff --git a/wpimath/src/main/native/include/frc/estimator/MecanumDrivePoseEstimator.h b/wpimath/src/main/native/include/frc/estimator/MecanumDrivePoseEstimator.h index 40d7e28436..76a31a0bf2 100644 --- a/wpimath/src/main/native/include/frc/estimator/MecanumDrivePoseEstimator.h +++ b/wpimath/src/main/native/include/frc/estimator/MecanumDrivePoseEstimator.h @@ -49,7 +49,7 @@ class WPILIB_DLLEXPORT MecanumDrivePoseEstimator { * Constructs a MecanumDrivePoseEstimator. * * @param gyroAngle The current gyro angle. - * @param initialPoseMeters The starting pose estimate. + * @param initialPose The starting pose estimate. * @param kinematics A correctly-configured kinematics object * for your drivetrain. * @param stateStdDevs Standard deviations of model states. @@ -102,8 +102,8 @@ class WPILIB_DLLEXPORT MecanumDrivePoseEstimator { *

The gyroscope angle does not need to be reset in the user's robot code. * The library automatically takes care of offsetting the gyro angle. * - * @param poseMeters The position on the field that your robot is at. - * @param gyroAngle The angle reported by the gyroscope. + * @param pose The position on the field that your robot is at. + * @param gyroAngle The angle reported by the gyroscope. */ void ResetPosition(const Pose2d& pose, const Rotation2d& gyroAngle); @@ -191,9 +191,9 @@ class WPILIB_DLLEXPORT MecanumDrivePoseEstimator { * information. This should be called every loop, and the correct loop period * must be passed into the constructor of this class. * - * @param currentTimeSeconds Time at which this method was called, in seconds. - * @param gyroAngle The current gyroscope angle. - * @param wheelSpeeds The current speeds of the mecanum drive wheels. + * @param currentTime Time at which this method was called, in seconds. + * @param gyroAngle The current gyroscope angle. + * @param wheelSpeeds The current speeds of the mecanum drive wheels. * @return The estimated pose of the robot in meters. */ Pose2d UpdateWithTime(units::second_t currentTime, diff --git a/wpimath/src/main/native/include/frc/estimator/SwerveDrivePoseEstimator.h b/wpimath/src/main/native/include/frc/estimator/SwerveDrivePoseEstimator.h index 67c955b3a4..e439622747 100644 --- a/wpimath/src/main/native/include/frc/estimator/SwerveDrivePoseEstimator.h +++ b/wpimath/src/main/native/include/frc/estimator/SwerveDrivePoseEstimator.h @@ -51,7 +51,7 @@ class SwerveDrivePoseEstimator { * Constructs a SwerveDrivePoseEstimator. * * @param gyroAngle The current gyro angle. - * @param initialPoseMeters The starting pose estimate. + * @param initialPose The starting pose estimate. * @param kinematics A correctly-configured kinematics object * for your drivetrain. * @param stateStdDevs Standard deviations of model states. diff --git a/wpimath/src/main/native/include/frc/fmt/Eigen.h b/wpimath/src/main/native/include/frc/fmt/Eigen.h index c78b597a92..f6cc7b6cc5 100644 --- a/wpimath/src/main/native/include/frc/fmt/Eigen.h +++ b/wpimath/src/main/native/include/frc/fmt/Eigen.h @@ -8,10 +8,25 @@ #include "Eigen/Core" +/** + * Formatter for Eigen::Matrix<>. + * + * @tparam Rows Number of rows. + * @tparam Cols Number of columns. + * @tparam Args Defaulted template arguments to Eigen::Matrix<>. + */ template struct fmt::formatter> { + /** + * Storage for format specifier. + */ char presentation = 'f'; + /** + * Format string parser. + * + * @param ctx Format string context. + */ constexpr auto parse(fmt::format_parse_context& ctx) { auto it = ctx.begin(), end = ctx.end(); if (it != end && (*it == 'f' || *it == 'e')) { @@ -25,6 +40,13 @@ struct fmt::formatter> { return it; } + /** + * Writes out a formatted matrix. + * + * @tparam FormatContext Format string context type. + * @param mat Matrix to format. + * @param ctx Format string context. + */ template auto format(const Eigen::Matrix& mat, FormatContext& ctx) { diff --git a/wpimath/src/main/native/include/frc/fmt/Units.h b/wpimath/src/main/native/include/frc/fmt/Units.h index 90633bcbc9..1ec61ca288 100644 --- a/wpimath/src/main/native/include/frc/fmt/Units.h +++ b/wpimath/src/main/native/include/frc/fmt/Units.h @@ -8,9 +8,28 @@ #include "units/base.h" +/** + * Formatter for unit types. + * + * @tparam Units Unit tag for which type of units the `unit_t` represents (e.g. + * meters). + * @tparam T Underlying type of the storage. Defaults to double. + * @tparam NonLinearScale Optional scale class for the units. Defaults to linear + * (i.e. does not scale the unit value). Examples of + * non-linear scales could be logarithmic, decibel, or + * richter scales. Non-linear scales must adhere to the + * non-linear-scale concept. + */ template class NonLinearScale> struct fmt::formatter> : fmt::formatter { + /** + * Writes out a formatted unit. + * + * @tparam FormatContext Format string context type. + * @param obj Unit instance. + * @param ctx Format string context. + */ template auto format(const units::unit_t& obj, FormatContext& ctx) { diff --git a/wpimath/src/main/native/include/frc/kinematics/SwerveDriveKinematics.h b/wpimath/src/main/native/include/frc/kinematics/SwerveDriveKinematics.h index 11298a1355..056f7c829d 100644 --- a/wpimath/src/main/native/include/frc/kinematics/SwerveDriveKinematics.h +++ b/wpimath/src/main/native/include/frc/kinematics/SwerveDriveKinematics.h @@ -51,8 +51,10 @@ class SwerveDriveKinematics { * pass in the module states in the same order when calling the forward * kinematics methods. * - * @param wheels The locations of the wheels relative to the physical center - * of the robot. + * @param wheel The location of the first wheel relative to the physical + * center of the robot. + * @param wheels The locations of the other wheels relative to the physical + * center of the robot. */ template explicit SwerveDriveKinematics(Translation2d wheel, Wheels&&... wheels) @@ -112,8 +114,9 @@ class SwerveDriveKinematics { * @return An array containing the module states. Use caution because these * module states are not normalized. Sometimes, a user input may cause one of * the module speeds to go above the attainable max velocity. Use the - * function to rectify this issue. In addition, you can - * leverage the power of C++17 to directly assign the module states to + * NormalizeWheelSpeeds(wpi::array*, + * units::meters_per_second_t) function to rectify this issue. In addition, + * you can leverage the power of C++17 to directly assign the module states to * variables: * * @code{.cpp} diff --git a/wpimath/src/main/native/include/frc/system/LinearSystem.h b/wpimath/src/main/native/include/frc/system/LinearSystem.h index 8b160a2997..5f12e3a663 100644 --- a/wpimath/src/main/native/include/frc/system/LinearSystem.h +++ b/wpimath/src/main/native/include/frc/system/LinearSystem.h @@ -106,9 +106,9 @@ class LinearSystem { * This is used by state observers directly to run updates based on state * estimate. * - * @param x The current state. - * @param u The control input. - * @param dt Timestep for model update. + * @param x The current state. + * @param clampedU The control input. + * @param dt Timestep for model update. */ Eigen::Vector CalculateX( const Eigen::Vector& x, diff --git a/wpimath/src/main/native/include/frc/system/LinearSystemLoop.h b/wpimath/src/main/native/include/frc/system/LinearSystemLoop.h index 9c5a01be18..9b77f35653 100644 --- a/wpimath/src/main/native/include/frc/system/LinearSystemLoop.h +++ b/wpimath/src/main/native/include/frc/system/LinearSystemLoop.h @@ -37,6 +37,7 @@ class LinearSystemLoop { * call reset with the initial system state before enabling the loop. This * constructor assumes that the input(s) to this system are voltage. * + * @param plant State-space plant. * @param controller State-space controller. * @param observer State-space observer. * @param maxVoltage The maximum voltage that can be applied. Commonly 12. diff --git a/wpimath/src/main/native/include/frc/trajectory/TrajectoryUtil.h b/wpimath/src/main/native/include/frc/trajectory/TrajectoryUtil.h index 308502b271..6e52a09318 100644 --- a/wpimath/src/main/native/include/frc/trajectory/TrajectoryUtil.h +++ b/wpimath/src/main/native/include/frc/trajectory/TrajectoryUtil.h @@ -21,8 +21,6 @@ class WPILIB_DLLEXPORT TrajectoryUtil { * * @param trajectory the trajectory to export * @param path the path of the file to export to - * - * @return The interpolated state. */ static void ToPathweaverJson(const Trajectory& trajectory, std::string_view path); @@ -38,19 +36,19 @@ class WPILIB_DLLEXPORT TrajectoryUtil { /** * Deserializes a Trajectory from PathWeaver-style JSON. * - * @param json the string containing the serialized JSON + * @param trajectory the trajectory to export * - * @return the trajectory represented by the JSON + * @return the string containing the serialized JSON */ static std::string SerializeTrajectory(const Trajectory& trajectory); /** * Serializes a Trajectory to PathWeaver-style JSON. * - * @param trajectory the trajectory to export + * @param jsonStr the string containing the serialized JSON * - * @return the string containing the serialized JSON + * @return the trajectory represented by the JSON */ - static Trajectory DeserializeTrajectory(std::string_view json_str); + static Trajectory DeserializeTrajectory(std::string_view jsonStr); }; } // namespace frc diff --git a/wpiutil/src/main/native/include/wpi/HttpServerConnection.h b/wpiutil/src/main/native/include/wpi/HttpServerConnection.h index 29006b178e..a4d4cf8caa 100644 --- a/wpiutil/src/main/native/include/wpi/HttpServerConnection.h +++ b/wpiutil/src/main/native/include/wpi/HttpServerConnection.h @@ -35,7 +35,7 @@ class HttpServerConnection { * Build common response headers. * * Called by SendHeader() to send headers common to every response. - * Each line must be terminated with \r\n. + * Each line must be terminated with "\r\n". * * The default implementation sends the following: * "Server: WebServer/1.0\r\n" diff --git a/wpiutil/src/main/native/include/wpi/SafeThread.h b/wpiutil/src/main/native/include/wpi/SafeThread.h index 4697c0d16d..bf3773243c 100644 --- a/wpiutil/src/main/native/include/wpi/SafeThread.h +++ b/wpiutil/src/main/native/include/wpi/SafeThread.h @@ -15,7 +15,9 @@ namespace wpi { -// Base class for SafeThreadOwner threads. +/** + * Base class for SafeThreadOwner threads. + */ class SafeThread { public: virtual ~SafeThread() = default; @@ -29,7 +31,9 @@ class SafeThread { namespace detail { -// Non-template proxy base class for common proxy code. +/** + * Non-template proxy base class for common proxy code. + */ class SafeThreadProxyBase { public: explicit SafeThreadProxyBase(std::shared_ptr thr); @@ -41,8 +45,11 @@ class SafeThreadProxyBase { std::unique_lock m_lock; }; -// A proxy for SafeThread. -// Also serves as a scoped lock on SafeThread::m_mutex. +/** + * A proxy for SafeThread. + * + * Also serves as a scoped lock on SafeThread::m_mutex. + */ template class SafeThreadProxy : public SafeThreadProxyBase { public: @@ -52,7 +59,9 @@ class SafeThreadProxy : public SafeThreadProxyBase { T* operator->() const { return static_cast(m_thread.get()); } }; -// Non-template owner base class for common owner code. +/** + * Non-template owner base class for common owner code. + */ class SafeThreadOwnerBase { public: void Stop(); diff --git a/wpiutil/src/main/native/include/wpi/Signal.h b/wpiutil/src/main/native/include/wpi/Signal.h index 64b774cf4d..d4993d9b51 100644 --- a/wpiutil/src/main/native/include/wpi/Signal.h +++ b/wpiutil/src/main/native/include/wpi/Signal.h @@ -565,7 +565,7 @@ public: * signal object, it does not cover thread safety of potentially * shared state used in slot functions. * - * @param a... arguments to emit + * @param a arguments to emit */ template void operator()(A && ... a) const { @@ -581,7 +581,6 @@ public: * Safety: Thread-safety depends on locking policy. * * @param c a callable - * @return a Connection object that can be used to interact with the slot */ template void connect(Callable && c) { diff --git a/wpiutil/src/main/native/include/wpi/UidVector.h b/wpiutil/src/main/native/include/wpi/UidVector.h index 9029f1a2c2..3ffd4c39c7 100644 --- a/wpiutil/src/main/native/include/wpi/UidVector.h +++ b/wpiutil/src/main/native/include/wpi/UidVector.h @@ -60,12 +60,15 @@ class UidVectorIterator { }; } // namespace impl -// Vector which provides an integrated freelist for removal and reuse of -// individual elements. -// @tparam T element type; must be default-constructible and evaluate in -// boolean context to false when "empty" -// @tparam reuse_threshold how many free elements to store up before starting -// to recycle them +/** + * Vector which provides an integrated freelist for removal and reuse of + * individual elements. + * + * @tparam T element type; must be default-constructible and evaluate in + * boolean context to false when "empty" + * @tparam reuse_threshold how many free elements to store up before starting + * to recycle them + */ template ::size_type reuse_threshold> class UidVector { public: @@ -103,8 +106,10 @@ class UidVector { return uid; } - // Removes the identified element by replacing it with a default-constructed - // one. The element is added to the freelist for later reuse. + /** + * Removes the identified element by replacing it with a default-constructed + * one. The element is added to the freelist for later reuse. + */ T erase(size_type uid) { if (uid >= m_vector.size() || !m_vector[uid]) { return T(); @@ -116,7 +121,9 @@ class UidVector { return rv; } - // Removes all elements. + /** + * Removes all elements. + */ void clear() noexcept { m_vector.clear(); m_free.clear(); diff --git a/wpiutil/src/main/native/include/wpi/WorkerThread.h b/wpiutil/src/main/native/include/wpi/WorkerThread.h index 915821b014..6c8852e4f7 100644 --- a/wpiutil/src/main/native/include/wpi/WorkerThread.h +++ b/wpiutil/src/main/native/include/wpi/WorkerThread.h @@ -225,6 +225,7 @@ class WorkerThread final { * destroyed while waiting for a result. * * @param work Work function (called on worker thread) + * @param u Arguments to work function */ template future QueueWork(WorkFunction work, U&&... u) { @@ -260,6 +261,7 @@ class WorkerThread final { * * @param work Work function (called on worker thread) * @param afterWork After work function (called on loop thread) + * @param u Arguments to work function */ template void QueueWorkThen(WorkFunction work, AfterWorkFunction afterWork, U&&... u) { diff --git a/wpiutil/src/main/native/include/wpi/jni_util.h b/wpiutil/src/main/native/include/wpi/jni_util.h index 3d1d02bf02..195e37e30b 100644 --- a/wpiutil/src/main/native/include/wpi/jni_util.h +++ b/wpiutil/src/main/native/include/wpi/jni_util.h @@ -26,15 +26,27 @@ /** Java Native Interface (JNI) utility functions */ namespace wpi::java { -// Gets a Java stack trace. Also provides the last function -// in the stack trace not starting with excludeFuncPrefix (useful for e.g. -// finding the first user call to a series of library functions). +/** + * Gets a Java stack trace. + * + * Also provides the last function in the stack trace not starting with + * excludeFuncPrefix (useful for e.g. finding the first user call to a series of + * library functions). + * + * @param env JRE environment. + * @param func Storage for last function in the stack trace not starting with + * excludeFuncPrefix. + * @param excludeFuncPrefix Prefix for functions to ignore in stack trace. + */ std::string GetJavaStackTrace(JNIEnv* env, std::string* func = nullptr, std::string_view excludeFuncPrefix = {}); -// Finds a class and keep it as a global reference. -// Use with caution, as the destructor does NOT call DeleteGlobalRef due -// to potential shutdown issues with doing so. +/** + * Finds a class and keeps it as a global reference. + * + * Use with caution, as the destructor does NOT call DeleteGlobalRef due to + * potential shutdown issues with doing so. + */ class JClass { public: JClass() = default; @@ -92,8 +104,11 @@ class JGlobal { T m_cls = nullptr; }; -// Container class for cleaning up Java local references. -// The destructor calls DeleteLocalRef. +/** + * Container class for cleaning up Java local references. + * + * The destructor calls DeleteLocalRef. + */ template class JLocal { public: @@ -126,9 +141,12 @@ class JLocal { // Conversions from Java objects to C++ // -// Java string (jstring) reference. The string is provided as UTF8. -// This is not actually a reference, as it makes a copy of the string -// characters, but it's named this way for consistency. +/** + * Java string (jstring) reference. + * + * The string is provided as UTF8. This is not actually a reference, as it makes + * a copy of the string characters, but it's named this way for consistency. + */ class JStringRef { public: JStringRef(JNIEnv* env, jstring str) { @@ -163,7 +181,9 @@ namespace detail { template class JArrayRefInner {}; -// Specialization of JArrayRefBase to provide std::string_view conversion. +/** + * Specialization of JArrayRefBase to provide std::string_view conversion. + */ template class JArrayRefInner { public: @@ -178,7 +198,9 @@ class JArrayRefInner { } }; -// Base class for J*ArrayRef and CriticalJ*ArrayRef +/** + * Base class for J*ArrayRef and CriticalJ*ArrayRef + */ template class JArrayRefBase : public JArrayRefInner, T> { public: @@ -329,7 +351,12 @@ WPI_JNI_JARRAYREF(jdouble, Double) // Conversions from C++ to Java objects // -// Convert a UTF8 string into a jstring. +/** + * Convert a UTF8 string into a jstring. + * + * @param env JRE environment. + * @param str String to convert. + */ inline jstring MakeJString(JNIEnv* env, std::string_view str) { SmallVector chars; convertUTF8ToUTF16String(str, chars); @@ -339,9 +366,12 @@ inline jstring MakeJString(JNIEnv* env, std::string_view str) { // details for MakeJIntArray namespace detail { -// Slow path (get primitive array and set individual elements). This -// is used if the input type is not an integer of the same size (note -// signed/unsigned is ignored). +/** + * Slow path (get primitive array and set individual elements). + * + * This is used if the input type is not an integer of the same size (note + * signed/unsigned is ignored). + */ template ::value && sizeof(jint) == sizeof(T))> struct ConvertIntArray { @@ -363,7 +393,9 @@ struct ConvertIntArray { } }; -// Fast path (use SetIntArrayRegion) +/** + * Fast path (use SetIntArrayRegion). + */ template struct ConvertIntArray { static jintArray ToJava(JNIEnv* env, span arr) { @@ -379,32 +411,62 @@ struct ConvertIntArray { } // namespace detail -// Convert an span to a jintArray. +/** + * Convert a span to a jintArray. + * + * @param env JRE environment. + * @param arr Span to convert. + */ template inline jintArray MakeJIntArray(JNIEnv* env, span arr) { return detail::ConvertIntArray::ToJava(env, arr); } +/** + * Convert a span to a jintArray. + * + * @param env JRE environment. + * @param arr Span to convert. + */ template inline jintArray MakeJIntArray(JNIEnv* env, span arr) { return detail::ConvertIntArray::ToJava(env, arr); } -// Convert a SmallVector to a jintArray. This is required in addition to -// ArrayRef because template resolution occurs prior to implicit conversions. +/** + * Convert a SmallVector to a jintArray. + * + * This is required in addition to ArrayRef because template resolution occurs + * prior to implicit conversions. + * + * @param env JRE environment. + * @param arr SmallVector to convert. + */ template inline jintArray MakeJIntArray(JNIEnv* env, const SmallVectorImpl& arr) { return detail::ConvertIntArray::ToJava(env, arr); } -// Convert a std::vector to a jintArray. This is required in addition to -// ArrayRef because template resolution occurs prior to implicit conversions. +/** + * Convert a std::vector to a jintArray. + * + * This is required in addition to ArrayRef because template resolution occurs + * prior to implicit conversions. + * + * @param env JRE environment. + * @param arr SmallVector to convert. + */ template inline jintArray MakeJIntArray(JNIEnv* env, const std::vector& arr) { return detail::ConvertIntArray::ToJava(env, arr); } -// Convert a std::string_view into a jbyteArray. +/** + * Convert a std::string_view into a jbyteArray. + * + * @param env JRE environment. + * @param str std::string_view to convert. + */ inline jbyteArray MakeJByteArray(JNIEnv* env, std::string_view str) { jbyteArray jarr = env->NewByteArray(str.size()); if (!jarr) { @@ -415,7 +477,12 @@ inline jbyteArray MakeJByteArray(JNIEnv* env, std::string_view str) { return jarr; } -// Convert an array of integers into a jbooleanArray. +/** + * Convert an array of integers into a jbooleanArray. + * + * @param env JRE environment. + * @param arr Array to convert. + */ inline jbooleanArray MakeJBooleanArray(JNIEnv* env, span arr) { jbooleanArray jarr = env->NewBooleanArray(arr.size()); if (!jarr) { @@ -433,7 +500,12 @@ inline jbooleanArray MakeJBooleanArray(JNIEnv* env, span arr) { return jarr; } -// Convert an array of booleans into a jbooleanArray. +/** + * Convert an array of booleans into a jbooleanArray. + * + * @param env JRE environment. + * @param arr Array to convert. + */ inline jbooleanArray MakeJBooleanArray(JNIEnv* env, span arr) { jbooleanArray jarr = env->NewBooleanArray(arr.size()); if (!jarr) { @@ -472,7 +544,12 @@ WPI_JNI_MAKEJARRAY(jdouble, Double) #undef WPI_JNI_MAKEJARRAY -// Convert an array of std::string into a jarray of jstring. +/** + * Convert an array of std::string into a jarray of jstring. + * + * @param env JRE environment. + * @param arr Array to convert. + */ inline jobjectArray MakeJStringArray(JNIEnv* env, span arr) { static JClass stringCls{env, "java/lang/String"}; if (!stringCls) { @@ -489,21 +566,23 @@ inline jobjectArray MakeJStringArray(JNIEnv* env, span arr) { return jarr; } -// Generic callback thread implementation. -// -// JNI's AttachCurrentThread() creates a Java Thread object on every -// invocation, which is both time inefficient and causes issues with Eclipse -// (which tries to keep a thread list up-to-date and thus gets swamped). -// -// Instead, this class attaches just once. When a hardware notification -// occurs, a condition variable wakes up this thread and this thread actually -// makes the call into Java. -// -// The template parameter T is the message being passed to the callback, but -// also needs to provide the following functions: -// static JavaVM* GetJVM(); -// static const char* GetName(); -// void CallJava(JNIEnv *env, jobject func, jmethodID mid); +/** + * Generic callback thread implementation. + * + * JNI's AttachCurrentThread() creates a Java Thread object on every + * invocation, which is both time inefficient and causes issues with Eclipse + * (which tries to keep a thread list up-to-date and thus gets swamped). + * + * Instead, this class attaches just once. When a hardware notification + * occurs, a condition variable wakes up this thread and this thread actually + * makes the call into Java. + * + * The template parameter T is the message being passed to the callback, but + * also needs to provide the following functions: + * static JavaVM* GetJVM(); + * static const char* GetName(); + * void CallJava(JNIEnv *env, jobject func, jmethodID mid); + */ template class JCallbackThread : public SafeThread { public: @@ -759,10 +838,13 @@ inline std::string GetJavaStackTrace(JNIEnv* env, std::string* func, return oss.str(); } -// Finds an exception class and keep it as a global reference. -// Similar to JClass, but provides Throw methods. -// Use with caution, as the destructor does NOT call DeleteGlobalRef due -// to potential shutdown issues with doing so. +/** + * Finds an exception class and keep it as a global reference. + * + * Similar to JClass, but provides Throw methods. Use with caution, as the + * destructor does NOT call DeleteGlobalRef due to potential shutdown issues + * with doing so. + */ class JException : public JClass { public: JException() = default; diff --git a/wpiutil/src/main/native/include/wpi/static_circular_buffer.h b/wpiutil/src/main/native/include/wpi/static_circular_buffer.h index b73ea48713..8cbf3fe64e 100644 --- a/wpiutil/src/main/native/include/wpi/static_circular_buffer.h +++ b/wpiutil/src/main/native/include/wpi/static_circular_buffer.h @@ -82,17 +82,38 @@ class static_circular_buffer { size_t m_index; }; + /** + * Returns begin iterator. + */ iterator begin() { return iterator(this, 0); } + + /** + * Returns end iterator. + */ iterator end() { return iterator(this, ::wpi::static_circular_buffer::size()); } + /** + * Returns begin iterator. + */ const_iterator begin() const { return const_iterator(this, 0); } + + /** + * Returns end iterator. + */ const_iterator end() const { return const_iterator(this, ::wpi::static_circular_buffer::size()); } + /** + * Returns begin iterator. + */ const_iterator cbegin() const { return const_iterator(this, 0); } + + /** + * Returns end iterator. + */ const_iterator cend() const { return const_iterator(this, ::wpi::static_circular_buffer::size()); }