Prefer line comments // over block comments /* */ (#2738)

* Prefer line comments // over block comments /* */

* esp-wifi: Prefer line comments // over block comments /* */

* Mention in our API guideline that // should be prefered over /* */

documentation/API-GUIDELINES.md

@@ -86,6 +86,7 @@ In general, the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines
 - Every line of code is a liability. Take some time to see if your implementation can be simplified before opening a PR.
 - If you are porting code from ESP-IDF (or anything else), please include a link WITH the commit hash in it, and please highlight the relevant line(s) of code
 - If necessary provide further context as comments (consider linking to code, PRs, TRM - make sure to use permanent links, e.g. include the hash when linking to a Git repository, include the revision, page number etc. when linking to TRMs)
+- Prefer line comments (//) to block comments (/* ... */)
 - Generally, follow common "good practices" and idiomatic Rust style
 - All `Future` objects (public or private) must be marked with ``#[must_use = "futures do nothing unless you `.await` or poll them"]``.
 - Prefer `cfg_if!` (or, if the branches just pick between separate values of the same variable, `cfg!()`) over multiple exclusive `#[cfg]` attributes. `cfg_if!`/`cfg!()` visually divide the options, often results in simpler conditions and simplifies adding new branches in the future.

esp-hal/src/rtc_cntl/rtc/esp32c6.rs

@@ -1361,7 +1361,7 @@ pub(crate) enum RtcFastClock {
 impl Clock for RtcFastClock {
     fn frequency(&self) -> HertzU32 {
         match self {
-            RtcFastClock::RtcFastClockXtalD2 => HertzU32::Hz(40_000_000 / 2), /* TODO: Is the value correct? */
+            RtcFastClock::RtcFastClockXtalD2 => HertzU32::Hz(40_000_000 / 2), // TODO: Is the value correct?
             RtcFastClock::RtcFastClockRcFast => HertzU32::Hz(17_500_000),
         }
     }

esp-hal/src/rtc_cntl/sleep/esp32c6.rs

@@ -728,23 +728,23 @@ impl SleepTimeConfig {
             );
 
         #[rustfmt::skip] // ASCII art
-        /* When the SOC wakeup (lp timer or GPIO wakeup) and Modem wakeup (Beacon wakeup) complete,
+        //  When the SOC wakeup (lp timer or GPIO wakeup) and Modem wakeup (Beacon wakeup) complete,
-        * the soc wakeup will be delayed until the RF is turned on in Modem state.
+        // the soc wakeup will be delayed until the RF is turned on in Modem state.
-        *
+        // 
-        *              modem wakeup                      TBTT, RF on by HW
+        //              modem wakeup                      TBTT, RF on by HW
-        *                   |                                    |
+        //                   |                                    |
-        *                  \|/                                  \|/
+        //                  \|/                                  \|/
-        * PMU_HP_ACTIVE                                                                         /------
+        // PMU_HP_ACTIVE                                                                         /------
-        * PMU_HP_MODEM                                           /------------//////////////////
+        // PMU_HP_MODEM                                           /------------//////////////////
-        * PMU_HP_SLEEP   ----------------------//////////////////
+        // PMU_HP_SLEEP   ----------------------//////////////////
-        *                  /|\                /|\ /|\          /|\           /|\              /|\
+        //                  /|\                /|\ /|\          /|\           /|\              /|\
-        *                   |<- some hw wait ->|   |            |             |<- M2A switch ->|
+        //                   |<- some hw wait ->|   |            |             |<- M2A switch ->|
-        *                   |  slow cycles &   | soc wakeup     |                              |
+        //                   |  slow cycles &   | soc wakeup     |                              |
-        *                   |   FOSC cycles    |<- S2M switch ->|                              |
+        //                   |   FOSC cycles    |<- S2M switch ->|                              |
-        *                   |                                                                  |
+        //                   |                                                                  |
-        *                   |<--      PMU guard time, also the maximum time for the SOC     -->|
+        //                   |<--      PMU guard time, also the maximum time for the SOC     -->|
-        *                   |                           wake-up delay                          |
+        //                   |                           wake-up delay                          |
-        */
+        // 
         const CONFIG_ESP_WIFI_ENHANCED_LIGHT_SLEEP: bool = true;
 
         let (rf_on_protect_time_us, sync_time_us) = if CONFIG_ESP_WIFI_ENHANCED_LIGHT_SLEEP {

esp-hal/src/spi/master.rs

@@ -2516,13 +2516,12 @@ impl Info {
             // Using APB frequency directly will give us the best result here.
             reg_val = 1 << 31;
         } else {
-            /* For best duty cycle resolution, we want n to be as close to 32 as
+            // For best duty cycle resolution, we want n to be as close to 32 as
-             * possible, but we also need a pre/n combo that gets us as close as
+            // possible, but we also need a pre/n combo that gets us as close as
-             * possible to the intended frequency. To do this, we bruteforce n and
+            // possible to the intended frequency. To do this, we bruteforce n and
-             * calculate the best pre to go along with that. If there's a choice
+            // calculate the best pre to go along with that. If there's a choice
-             * between pre/n combos that give the same result, use the one with the
+            // between pre/n combos that give the same result, use the one with the
-             * higher n.
+            // higher n.
-             */
 
             let mut pre: i32;
             let mut bestn: i32 = -1;
@@ -2530,14 +2529,12 @@ impl Info {
             let mut besterr: i32 = 0;
             let mut errval: i32;
 
-            /* Start at n = 2. We need to be able to set h/l so we have at least
+            // Start at n = 2. We need to be able to set h/l so we have at least
-             * one high and one low pulse.
+            // one high and one low pulse.
-             */
 
             for n in 2..64 {
-                /* Effectively, this does:
+                // Effectively, this does:
-                 *   pre = round((APB_CLK_FREQ / n) / frequency)
+                // pre = round((APB_CLK_FREQ / n) / frequency)
-                 */
 
                 pre = ((apb_clk_freq.raw() as i32 / n) + (frequency.raw() as i32 / 2))
                     / frequency.raw() as i32;
@@ -2562,9 +2559,8 @@ impl Info {
             pre = bestpre;
             let l: i32 = n;
 
-            /* Effectively, this does:
+            // Effectively, this does:
-             *   h = round((duty_cycle * n) / 256)
+            // h = round((duty_cycle * n) / 256)
-             */
 
             let mut h: i32 = (duty_cycle * n + 127) / 256;
             if h <= 0 {

esp-wifi/src/ble/btdm.rs

@@ -25,11 +25,13 @@ static PACKET_SENT: AtomicBool = AtomicBool::new(true);
 
 #[repr(C)]
 struct VhciHostCallbacks {
-    notify_host_send_available: extern "C" fn(), /* callback used to notify that the host can
+    // callback used to notify that the host can
-                                                  * send packet to controller */
+    // send packet to controller
-    notify_host_recv: extern "C" fn(*mut u8, u16) -> i32, /* callback used to notify that the
+    notify_host_send_available: extern "C" fn(),
-                                                           * controller has a packet to send to
+    // callback used to notify that the
-                                                           * the host */
+    // controller has a packet to send to
+    // the host
+    notify_host_recv: extern "C" fn(*mut u8, u16) -> i32,
 }
 
 extern "C" {

esp-wifi/src/ble/npl.rs

@@ -233,9 +233,11 @@ extern "C" {
     pub(crate) fn bt_bb_v2_init_cmplx(value: u8);
 
     pub(crate) fn r_ble_hci_trans_cfg_hs(
-        evt: Option<unsafe extern "C" fn(cmd: *const u8, arg: *const c_void) -> i32>, /* ble_hci_trans_rx_cmd_fn */
+        // ble_hci_trans_rx_cmd_fn
+        evt: Option<unsafe extern "C" fn(cmd: *const u8, arg: *const c_void) -> i32>,
         evt_arg: *const c_void,
-        acl_cb: Option<unsafe extern "C" fn(om: *const OsMbuf, arg: *const c_void) -> i32>, /* ble_hci_trans_rx_acl_fn */
+        // ble_hci_trans_rx_acl_fn
+        acl_cb: Option<unsafe extern "C" fn(om: *const OsMbuf, arg: *const c_void) -> i32>,
         acl_arg: *const c_void,
     );