docs review

nRF24 · Oct 24, 2024 · 41e21eb · 41e21eb
1 parent 2d43231
commit 41e21eb
Show file tree

Hide file tree

Showing 4 changed files with 55 additions and 40 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 <!-- markdownlint-disable MD041 -->
-[![build and test CI][build-ci-badge]][build-ci-runs] [![codecov][codecov-badge]][codecov-project]
+[![Python builds][python-ci-badge]][python-ci] [![Node.js Builds][node-js-ci-badge]][node-js-ci] [![Tests][test-ci-badge]][test-ci] [![codecov][codecov-badge]][codecov-project] [![Docs][docs-ci-badge]][docs-ci] [![Examples][examples-ci-badge]][examples-ci]
 
 # rf24-rs
 
@@ -38,8 +38,16 @@ but they all seem unmaintained or designed to be application-specific. There's e
 a [crate to use the nRF5x chips' ESB support][crate-esb], but this too seems lacking
 maintainers' attention.
 
-[build-ci-badge]: https://github.com/nRF24/rf24-rs/actions/workflows/tests.yml/badge.svg
-[build-ci-runs]: https://github.com/nRF24/rf24-rs/actions/workflows/tests.yml
+[python-ci-badge]: https://github.com/nRF24/rf24-rs/actions/workflows/python-packaging.yml/badge.svg
+[python-ci]: https://github.com/nRF24/rf24-rs/actions/workflows/python-packaging.yml
+[node-js-ci-badge]: https://github.com/nRF24/rf24-rs/actions/workflows/node-packaging.yml/badge.svg
+[node-js-ci]: https://github.com/nRF24/rf24-rs/actions/workflows/node-packaging.yml
+[docs-ci-badge]: https://github.com/nRF24/rf24-rs/actions/workflows/docs.yml/badge.svg
+[docs-ci]: https://github.com/nRF24/rf24-rs/actions/workflows/docs.yml
+[examples-ci-badge]: https://github.com/nRF24/rf24-rs/actions/workflows/examples.yml/badge.svg
+[examples-ci]: https://github.com/nRF24/rf24-rs/actions/workflows/examples.yml
+[test-ci-badge]: https://github.com/nRF24/rf24-rs/actions/workflows/tests.yml/badge.svg
+[test-ci]: https://github.com/nRF24/rf24-rs/actions/workflows/tests.yml
 [codecov-badge]: https://codecov.io/gh/nRF24/rf24-rs/graph/badge.svg?token=BMQ97Y5RVP
 [codecov-project]: https://codecov.io/gh/nRF24/rf24-rs
 [embedded-rs]: https://docs.rust-embedded.org/book/

diff --git a/bindings/node/src/radio.rs b/bindings/node/src/radio.rs
@@ -131,10 +131,6 @@ impl RF24 {
 
     /// Put the radio into active RX mode.
     ///
-    /// > [!WARNING]
-    /// > Do not call {@link RF24.send} while in active RX mode because (internally in rust)
-    /// > that _will_ cause an infinite loop.
-    ///
     /// @group Basic
     #[napi]
     pub fn start_listening(&mut self) -> Result<()> {
@@ -147,6 +143,10 @@ impl RF24 {
     ///
     /// The datasheet recommends idling the radio in an inactive TX mode.
     ///
+    /// > [!NOTE]
+    /// > This function will also flush the TX FIFO when ACK payloads are enabled
+    /// > (via {@link RF24.allowAckPayloads | `RF24.allowAckPayloads()`}).
+    ///
     /// @group Basic
     #[napi]
     pub fn stop_listening(&mut self) -> Result<()> {
@@ -185,7 +185,7 @@ impl RF24 {
     /// @param buf - The buffer of bytes to load into the TX FIFO.
     ///
     /// @returns A Boolean that describes if the given `buf` was successfully loaded
-    /// into the TX FIFO.
+    /// into the TX FIFO. Remember, the TX FIFO has only 3 levels ("slots").
     ///
     /// @group Advanced
     #[napi]
@@ -622,7 +622,7 @@ impl RF24 {
 
     /// Enable or disable the dynamically sized payloads feature.
     ///
-    /// @param enable - If set to `true`, the statically sized payloads (set via
+    /// @param enable - If set to `true`, the statically sized payload length (set via
     /// {@link RF24.setPayloadLength | `RF24.setPayloadLength()`}) are not used.
     ///
     /// @group Configuration
@@ -762,7 +762,7 @@ impl RF24 {
 
     /// Configure the IRQ pin to reflect the specified {@link StatusFlags | `StatusFlags`}.
     ///
-    /// If no parameter value is given, then all flags are are reflected by the IRQ pin.
+    /// @param flags - If no value is given, then all flags are reflected by the IRQ pin.
     ///
     /// @group Configuration
     #[napi]
@@ -779,7 +779,7 @@ impl RF24 {
 
     /// Reset the specified {@link StatusFlags | `StatusFlags`}.
     ///
-    /// If no parameter value is given, then all flags are reset.
+    /// @param flags - If no value is given, then all flags are reset.
     ///
     /// @group Advanced
     #[napi]
@@ -796,7 +796,7 @@ impl RF24 {
 
     /// Update the cached value of Status flags.
     ///
-    /// Use {@link RF24.getStatusFlags | `RF24.getStatusFlags`} to get the updated values.
+    /// Use {@link RF24.getStatusFlags | `RF24.getStatusFlags()`} to get the updated values.
     ///
     /// @group Advanced
     #[napi]

diff --git a/bindings/python/src/radio.rs b/bindings/python/src/radio.rs
@@ -134,10 +134,6 @@ impl RF24 {
     }
 
     /// Put the radio into active RX mode.
-    ///
-    /// Warning:
-    ///     Do not call [`RF24.send()`][rf24_py.RF24.send] while in active RX mode
-    ///     because (internally in rust) that _will_ cause an infinite loop.
     pub fn start_listening(&mut self) -> PyResult<()> {
         self.inner
             .start_listening()
@@ -147,6 +143,10 @@ impl RF24 {
     /// Deactivates active RX mode and puts the radio into an inactive TX mode.
     ///
     /// The datasheet recommends idling the radio in an inactive TX mode.
+    ///
+    /// Note:
+    ///     This function will also flush the TX FIFO when ACK payloads are enabled
+    ///     (via [`RF24.allow_ack_payloads()`][rf24_py.RF24.allow_ack_payloads]).
     pub fn stop_listening(&mut self) -> PyResult<()> {
         self.inner
             .stop_listening()
@@ -333,9 +333,9 @@ impl RF24 {
 
     /// Enable or disable the auto-ack feature for all pipes.
     ///
-    /// > [!NOTE]
-    /// > This feature requires CRC to be enabled.
-    /// > See [`RF24.crc_length`][rf24_py.RF24.crc_length] for more detail.
+    /// Note:
+    ///     This feature requires CRC to be enabled.
+    ///     See [`RF24.crc_length`][rf24_py.RF24.crc_length] for more detail.
     ///
     /// Parameters:
     ///     enable: Pass true to enable the auto-ack feature for all pipes.
@@ -347,6 +347,10 @@ impl RF24 {
 
     /// Enable or disable the auto-ack feature for a specified `pipe`.
     ///
+    /// Note:
+    ///     This feature requires CRC to be enabled.
+    ///     See [`RF24.crc_length`][rf24_py.RF24.crc_length] for more detail.
+    ///
     /// Parameters:
     ///     enable: Pass true to enable the auto-ack feature for the specified `pipe`.
     ///     pipe: The pipe about which to control the auto-ack feature.
@@ -381,7 +385,7 @@ impl RF24 {
     ///
     /// Returns:
     ///     A boolean value that describes if the payload was successfully uploaded
-    ///     to the TX FIFO. Remember, the TX FIFO only has 3 levels ("slots").
+    ///         to the TX FIFO. Remember, the TX FIFO only has 3 levels ("slots").
     pub fn write_ack_payload(&mut self, pipe: u8, buf: &[u8]) -> PyResult<bool> {
         self.inner
             .write_ack_payload(pipe, buf)
@@ -408,7 +412,7 @@ impl RF24 {
             .map_err(|e| PyRuntimeError::new_err(format!("{e:?}")))
     }
 
-    /// Set the channel (frequency) that the radio uses to transmit and receive.
+    /// Set/get the channel (frequency) that the radio uses to transmit and receive.
     ///
     /// The channel must be in range [0, 125], otherwise this
     /// function does nothing. This value can be roughly translated into frequency
@@ -551,7 +555,7 @@ impl RF24 {
     /// Enable or disable the dynamically sized payloads feature.
     ///
     /// Parameters:
-    ///     enable: If set to `true`, the statically sized payloads (set via
+    ///     enable: If set to `true`, the statically sized payload length (set via
     ///         [`RF24.payload_length`][rf24_py.RF24.payload_length]) are not
     ///         used.
     pub fn set_dynamic_payloads(&mut self, enable: bool) -> PyResult<()> {
@@ -576,10 +580,10 @@ impl RF24 {
     /// It is highly recommended to avoid using pip 0 to receive because it is also
     /// used to transmit automatic acknowledgements.
     ///
-    /// > [!NOTE]
-    /// > Only pipes 0 and 1 actually use up to 5 bytes of the given address.
-    /// > Pipes 2 - 5 only use the first byte of the given address and last 4
-    /// > bytes of the address set to pipe 1.
+    /// Note:
+    ///     Only pipes 0 and 1 actually use up to 5 bytes of the given address.
+    ///     Pipes 2 - 5 only use the first byte of the given address and last 4
+    ///     bytes of the address set to pipe 1.
     ///
     /// Parameters:
     ///     pipe: The pipe number to receive data. This must be in range [0, 5],
@@ -683,7 +687,9 @@ impl RF24 {
 
     /// Configure the IRQ pin to reflect the specified [`StatusFlags`][rf24_py.StatusFlags].
     ///
-    /// If no parameter value is given, then all flags are are reflected by the IRQ pin.
+    /// Other Parameters:
+    ///     flags: If this value is `None`, then all flags are reflected by the IRQ pin.
+    ///
     #[pyo3(signature = (flags = None))]
     pub fn set_status_flags(&mut self, flags: Option<StatusFlags>) -> PyResult<()> {
         let flags = flags.map(|f| f.into_inner());
@@ -694,7 +700,8 @@ impl RF24 {
 
     /// Reset the specified [`StatusFlags`][rf24_py.StatusFlags].
     ///
-    /// If no parameter value is given, then all flags are reset.
+    /// Other Parameters:
+    ///     flags: If this value is `None`, then all flags are reset.
     #[pyo3(signature = (flags = None))]
     pub fn clear_status_flags(&mut self, flags: Option<StatusFlags>) -> PyResult<()> {
         let flags = flags.map(|f| f.into_inner());
@@ -714,12 +721,12 @@ impl RF24 {
 
     /// Get the current state of the [`StatusFlags`][rf24_py.StatusFlags].
     ///
-    /// > [!NOTE]
-    /// > This function simply returns the value of the flags that was cached
-    /// > from the last SPI transaction. It does not actually update the values
-    /// > (from the radio) before returning them.
-    /// >
-    /// > Use [`RF24.update`][rf24_py.RF24.update] to update them first.
+    /// Note:
+    ///     This function simply returns the value of the flags that was cached
+    ///     from the last SPI transaction. It does not actually update the values
+    ///     (from the radio) before returning them.
+    ///
+    ///     Use [`RF24.update()`][rf24_py.RF24.update] to update them first.
     pub fn get_status_flags(&mut self) -> StatusFlags {
         let mut flags = rf24::StatusFlags::default();
         self.inner.get_status_flags(&mut flags);

diff --git a/bindings/python/src/types.rs b/bindings/python/src/types.rs
@@ -106,6 +106,12 @@ impl PaLevel {
     }
 }
 
+/// How fast data moves through the air. Units are in bits per second (bps).
+///
+/// Attributes:
+///     Mbps1: Represents 1 Mbps
+///     Mbps2: Represents 2 Mbps
+///     Kbps250: Represents 250 Kbps
 #[pyclass(eq, eq_int, module = "rf24_py")]
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum DataRate {
@@ -114,12 +120,6 @@ pub enum DataRate {
     Kbps250,
 }
 
-/// How fast data moves through the air. Units are in bits per second (bps).
-///
-/// Attributes:
-///     Mbps1: Represents 1 Mbps
-///     Mbps2: Represents 2 Mbps
-///     Kbps250: Represents 250 Kbps
 #[cfg(target_os = "linux")]
 impl DataRate {
     pub fn into_inner(self) -> rf24::DataRate {