Simplify/clarify some docs/syntax in wifi code (#4294)

* Simplify

* Clarify docs

* Rename blocking function, fix links to items

Author: bugadani

esp-radio/CHANGELOG.md

@@ -53,6 +53,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - The `ieee802154_rx_queue_size` config option has been replaced by a runtime option in `esp_radio::ieee802154::Config` (#4224)
 - The default value of `wifi_max_burst_size` has been changed to 3 (#4231)
 - Set `ble_ll_sync_cnt` to 0 on C6, C2 and H2 as in esp-idf Kconfig default (#4241)
+- `esp_radio::wifi::WifiController::scan_with_config_sync` has been renamed to `scan_with_config` (#4294)
 
 ### Fixed
 

esp-radio/MIGRATING-0.15.0.md

@@ -65,7 +65,7 @@ Provide these symbols:
 
 ## Scanning Functions
 
-The `scan_with_config_sync_max`, `scan_with_config_sync_max`, `scan_n`, and `scan_n_async` functions have been removed. You can instead use the `scan_with_config_async` or `scan_with_config_sync` funtions while specifying a `max` value in `ScanConfig`.
+The `scan_with_config_sync_max`, `scan_with_config_sync_max`, `scan_n`, and `scan_n_async` functions have been removed. You can instead use the `scan_with_config_async` or `scan_with_config` functions while specifying a `max` value in `ScanConfig`.
 
 ## Configuration
 

esp-radio/src/wifi/mod.rs

@@ -3022,7 +3022,7 @@ impl WifiController<'_> {
     }
 
     /// A blocking wifi network scan with caller-provided scanning options.
-    pub fn scan_with_config_sync(
+    pub fn scan_with_config(
         &mut self,
         config: ScanConfig<'_>,
     ) -> Result<alloc::vec::Vec<AccessPointInfo>, WifiError> {
@@ -3055,6 +3055,9 @@ impl WifiController<'_> {
     }
 
     /// Starts the Wi-Fi controller.
+    ///
+    /// This method is not blocking. To check if the controller has started, use the
+    /// [`Self::is_started`] method.
     pub fn start(&mut self) -> Result<(), WifiError> {
         unsafe {
             esp_wifi_result!(esp_wifi_start())?;
@@ -3080,21 +3083,31 @@ impl WifiController<'_> {
     }
 
     /// Stops the Wi-Fi controller.
+    ///
+    /// This method is not blocking. Use the [`Self::is_started`] method to see if the controller is
+    /// still running.
     pub fn stop(&mut self) -> Result<(), WifiError> {
         self.stop_impl()
     }
 
     /// Connect Wi-Fi station to the AP.
     ///
-    /// - If station is connected , call [Self::disconnect] to disconnect.
-    /// - Scanning will not be effective until connection between device and the AP is established.
+    /// This method is not blocking. Use the [`Self::is_connected`] method to see if the station is
+    /// connected.
+    ///
+    /// - If station is connected, call [`Self::disconnect`] to disconnect.
+    /// - Calling [`Self::scan_with_config`] or [`Self::scan_with_config_async`] will not be
+    ///   effective until connection between device and the AP is established.
     /// - If device is scanning and connecting at the same time, it will abort scanning and return a
-    ///   warning message and error
+    ///   warning message and error.
     pub fn connect(&mut self) -> Result<(), WifiError> {
         self.connect_impl()
     }
 
     /// Disconnect Wi-Fi station from the AP.
+    ///
+    /// This method is not blocking. Use the [`Self::is_connected`] method to see if the station is
+    /// still connected.
     pub fn disconnect(&mut self) -> Result<(), WifiError> {
         self.disconnect_impl()
     }
@@ -3104,12 +3117,12 @@ impl WifiController<'_> {
     ///
     /// <div class="warning">
     ///
-    /// - This API should be called after station connected to AP.
     /// - Use this API only in STA or AP-STA mode.
+    /// - This API should be called after the station has connected to an access point.
     /// </div>
     ///
     /// # Errors
-    /// This function returns [WifiError::Unsupported] if the STA side isn't
+    /// This function returns [`WifiError::Unsupported`] if the STA side isn't
     /// running. For example, when configured for AP only.
     pub fn rssi(&self) -> Result<i32, WifiError> {
         if self.mode()?.is_sta() {
@@ -3133,9 +3146,9 @@ impl WifiController<'_> {
     /// Set the configuration.
     ///
     /// This will set the mode accordingly.
-    /// You need to use Wifi::connect() for connecting to an AP.
+    /// You need to use [`Self::connect`] for connecting to an AP.
     ///
-    /// Passing [ModeConfig::None] will disable both, AP and STA mode.
+    /// Passing [`ModeConfig::None`] will disable both, AP and STA mode.
     ///
     /// If you don't intend to use Wi-Fi anymore at all consider tearing down
     /// Wi-Fi completely.
@@ -3187,7 +3200,7 @@ impl WifiController<'_> {
 
     /// Set the Wi-Fi mode.
     ///
-    /// This will override the mode inferred by [Self::set_config].
+    /// This will override the mode inferred by [`Self::set_config`].
     pub fn set_mode(&mut self, mode: WifiMode) -> Result<(), WifiError> {
         esp_wifi_result!(unsafe { esp_wifi_set_mode(mode.into()) })?;
         Ok(())
@@ -3209,8 +3222,8 @@ impl WifiController<'_> {
 
     /// Checks if the Wi-Fi controller has started. Returns true if STA and/or AP are started.
     ///
-    /// This function should be called after the `start` method to verify if the
-    /// Wi-Fi has started successfully.
+    /// This function should be called after the [`Self::start`] method to verify if the
+    /// Wi-Fi controller has started successfully.
     pub fn is_started(&self) -> Result<bool, WifiError> {
         if matches!(
             crate::wifi::sta_state(),
@@ -3226,7 +3239,7 @@ impl WifiController<'_> {
 
     /// Checks if the Wi-Fi controller is connected to an AP.
     ///
-    /// This function should be called after the `connect` method to verify if
+    /// This function should be called after the [`Self::connect`] method to verify if
     /// the connection was successful.
     pub fn is_connected(&self) -> Result<bool, WifiError> {
         match crate::wifi::sta_state() {
@@ -3260,7 +3273,9 @@ impl WifiController<'_> {
         Ok(result)
     }
 
-    /// Async version of [`crate::wifi::WifiController`]'s `start` method
+    /// Async version of [`Self::start`].
+    ///
+    /// This function will wait for the Wi-Fi controller to start before returning.
     pub async fn start_async(&mut self) -> Result<(), WifiError> {
         let mut events = enumset::enum_set! {};
 
@@ -3281,7 +3296,9 @@ impl WifiController<'_> {
         Ok(())
     }
 
-    /// Async version of [`crate::wifi::WifiController`]'s `stop` method
+    /// Async version of [`Self::stop`].
+    ///
+    /// This function will wait for the Wi-Fi controller to stop before returning.
     pub async fn stop_async(&mut self) -> Result<(), WifiError> {
         let mut events = enumset::enum_set! {};
 
@@ -3295,7 +3312,7 @@ impl WifiController<'_> {
 
         Self::clear_events(events);
 
-        crate::wifi::WifiController::stop_impl(self)?;
+        self.stop_impl()?;
 
         self.wait_for_all_events(events, false).await;
 
@@ -3305,11 +3322,13 @@ impl WifiController<'_> {
         Ok(())
     }
 
-    /// Async version of [`crate::wifi::WifiController`]'s `connect` method
+    /// Async version of [`Self::connect`].
+    ///
+    /// This function will wait for the connection to be established before returning.
     pub async fn connect_async(&mut self) -> Result<(), WifiError> {
         Self::clear_events(WifiEvent::StaConnected | WifiEvent::StaDisconnected);
 
-        let err = crate::wifi::WifiController::connect_impl(self).err();
+        let err = self.connect_impl().err();
 
         if MultiWifiEventFuture::new(WifiEvent::StaConnected | WifiEvent::StaDisconnected)
             .await
@@ -3321,8 +3340,9 @@ impl WifiController<'_> {
         }
     }
 
-    /// Async version of [`crate::wifi::WifiController`]'s `Disconnect`
-    /// method
+    /// Async version of [`Self::disconnect`].
+    ///
+    /// This function will wait for the connection to be closed before returning.
     pub async fn disconnect_async(&mut self) -> Result<(), WifiError> {
         // If not connected, this will do nothing.
         // It will also wait forever for a `StaDisconnected` event that will never come.
@@ -3332,7 +3352,7 @@ impl WifiController<'_> {
         }
 
         Self::clear_events(WifiEvent::StaDisconnected);
-        crate::wifi::WifiController::disconnect_impl(self)?;
+        self.disconnect_impl()?;
         WifiEventFuture::new(WifiEvent::StaDisconnected).await;
 
         Ok(())

examples/wifi/dhcp/src/main.rs

@@ -95,7 +95,7 @@ fn main() -> ! {
 
     println!("Start Wifi Scan");
     let scan_config = ScanConfig::default().with_max(10);
-    let res = controller.scan_with_config_sync(scan_config).unwrap();
+    let res = controller.scan_with_config(scan_config).unwrap();
     for ap in res {
         println!("{:?}", ap);
     }

examples/wifi/static_ip/src/main.rs

@@ -83,7 +83,7 @@ fn main() -> ! {
 
     println!("Start Wifi Scan");
     let scan_config = ScanConfig::default().with_max(10);
-    let res = controller.scan_with_config_sync(scan_config).unwrap();
+    let res = controller.scan_with_config(scan_config).unwrap();
     for ap in res {
         println!("{:?}", ap);
     }

qa-test/src/bin/wifi_bench.rs

@@ -114,7 +114,7 @@ fn main() -> ! {
 
     println!("Start Wifi Scan");
     let scan_config = ScanConfig::default().with_max(10);
-    let res = controller.scan_with_config_sync(scan_config).unwrap();
+    let res = controller.scan_with_config(scan_config).unwrap();
     for ap in res {
         println!("{:?}", ap);
     }

qa-test/src/bin/wifi_csi.rs

@@ -96,7 +96,7 @@ fn main() -> ! {
     println!("Waiting for CSI data...");
     println!("Start Wifi Scan");
     let scan_config = ScanConfig::default().with_max(10);
-    let res = controller.scan_with_config_sync(scan_config).unwrap();
+    let res = controller.scan_with_config(scan_config).unwrap();
     for ap in res {
         println!("{:?}", ap);
     }