docs review

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/

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
@@ -649,7 +649,7 @@ impl RF24 {
 
     /// Open a specific pipe for receiving from the given address.
     ///
-    /// It is highly recommended to avoid using pip 0 to receive because it is also
+    /// It is highly recommended to avoid using pipe 0 to receive because it is also
     /// used to transmit automatic acknowledgements.
     ///
     /// > [!NOTE]
@@ -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]

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<()> {
@@ -573,13 +577,13 @@ impl RF24 {
 
     /// Open a specific pipe for receiving from the given address.
     ///
-    /// It is highly recommended to avoid using pip 0 to receive because it is also
+    /// It is highly recommended to avoid using pipe 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);

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 {

docs/package.json

@@ -8,6 +8,6 @@
     },
     "license": "MIT",
     "scripts": {
-        "build": "npx typedoc ../bindings/node/index.d.ts --out ./src/node-api --json node-api.json"
+        "build": "npx typedoc ../bindings/node/index.d.ts --out ./src/node-api"
     }
 }

docs/scripts/html_sanitizer.py

@@ -15,6 +15,7 @@
 DEFINED_IN_PATTERN = re.compile(r"#### Defined in\n\nindex\.d\.ts\:\d+")
 SECTIONS_PATTERN = re.compile(r"#### (Parameters|Returns|Throws)")
 LIST_MARKER_PATTERN = re.compile("^• ", re.MULTILINE)
+GROUP_API_PATTERN = re.compile(r"^## \w+\s*$", re.MULTILINE)
 
 
 def on_page_markdown(
@@ -31,7 +32,38 @@ def on_page_markdown(
     # remove copy button from all signatures
     markdown = markdown.replace("```ts", "``` { .ts .no-copy }")
     markdown = LIST_MARKER_PATTERN.sub("- ", markdown)
-    return markdown
+    if page.file.src_path != "node-api/classes/RF24.md":
+        return markdown
+    # Now rearrange the grouped API of the RF24 class.
+    # By default, output is grouped in alphabetical order. We want
+    # 1. Basic
+    # 2. Advanced
+    # 3. Configuration
+    result = ""
+    basic_api_span = []
+    advanced_api_span = []
+    configure_api_span = []
+    for index, match in enumerate(GROUP_API_PATTERN.finditer(markdown)):
+        if index == 0:
+            result += markdown[: match.start()]
+        if "Basic" in match.group(0):
+            basic_api_span.append(match.start())
+            advanced_api_span.append(match.start())
+        elif "Advanced" in match.group(0):
+            advanced_api_span.append(match.start())
+        elif "Configuration" in match.group(0):
+            basic_api_span.append(match.start())
+            configure_api_span.extend([match.start(), len(markdown)])
+    result += markdown[basic_api_span[0] : basic_api_span[1]].replace(
+        "## Basic", "## Basic API", count=1
+    )
+    result += markdown[advanced_api_span[0] : advanced_api_span[1]].replace(
+        "## Advanced", "## Advanced API", count=1
+    )
+    result += markdown[configure_api_span[0] : configure_api_span[1]].replace(
+        "## Configuration", "## Configuration API", count=1
+    )
+    return result
 
 
 def on_page_content(html: str, page: Page, config: MkDocsConfig, files: Files) -> str:

docs/src/index.md

@@ -10,3 +10,4 @@ The Rust API documentation is hosted at [docs.rs](https://docs.rs/rf24).
 Here, you will find the API for FFI (Foreign Function Interface) bindings:
 
 - [Node.js bindings](node-api/README.md)
+- [Python bindings](python-api/README.md)