From 3a03dd88c774b68533f7c539c7480d19f05fc9ec Mon Sep 17 00:00:00 2001 From: Juraj Sadel Date: Thu, 12 Dec 2024 16:53:38 +0100 Subject: [PATCH] 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 | 1 + esp-hal/src/rtc_cntl/rtc/esp32c6.rs | 2 +- esp-hal/src/rtc_cntl/sleep/esp32c6.rs | 34 +++++++++++++-------------- esp-hal/src/spi/master.rs | 28 ++++++++++------------ esp-wifi/src/ble/btdm.rs | 12 ++++++---- esp-wifi/src/ble/npl.rs | 6 +++-- 6 files changed, 42 insertions(+), 41 deletions(-) diff --git a/documentation/API-GUIDELINES.md b/documentation/API-GUIDELINES.md index 535d2faa0ea..28808aef144 100644 --- a/documentation/API-GUIDELINES.md +++ b/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. diff --git a/esp-hal/src/rtc_cntl/rtc/esp32c6.rs b/esp-hal/src/rtc_cntl/rtc/esp32c6.rs index 66d72abf62c..5e0d40f7533 100644 --- a/esp-hal/src/rtc_cntl/rtc/esp32c6.rs +++ b/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), } } diff --git a/esp-hal/src/rtc_cntl/sleep/esp32c6.rs b/esp-hal/src/rtc_cntl/sleep/esp32c6.rs index e874617b7a8..7282e3a1392 100644 --- a/esp-hal/src/rtc_cntl/sleep/esp32c6.rs +++ b/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, - * the soc wakeup will be delayed until the RF is turned on in Modem state. - * - * modem wakeup TBTT, RF on by HW - * | | - * \|/ \|/ - * PMU_HP_ACTIVE /------ - * PMU_HP_MODEM /------------////////////////// - * PMU_HP_SLEEP ----------------------////////////////// - * /|\ /|\ /|\ /|\ /|\ /|\ - * |<- some hw wait ->| | | |<- M2A switch ->| - * | slow cycles & | soc wakeup | | - * | FOSC cycles |<- S2M switch ->| | - * | | - * |<-- PMU guard time, also the maximum time for the SOC -->| - * | wake-up delay | - */ + // 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. + // + // modem wakeup TBTT, RF on by HW + // | | + // \|/ \|/ + // PMU_HP_ACTIVE /------ + // PMU_HP_MODEM /------------////////////////// + // PMU_HP_SLEEP ----------------------////////////////// + // /|\ /|\ /|\ /|\ /|\ /|\ + // |<- some hw wait ->| | | |<- M2A switch ->| + // | slow cycles & | soc wakeup | | + // | FOSC cycles |<- S2M switch ->| | + // | | + // |<-- PMU guard time, also the maximum time for the SOC -->| + // | 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 { diff --git a/esp-hal/src/spi/master.rs b/esp-hal/src/spi/master.rs index 51a17f9f4b5..0d3e7badc39 100644 --- a/esp-hal/src/spi/master.rs +++ b/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 - * 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 - * 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 - * higher n. - */ + // 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 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 + // between pre/n combos that give the same result, use the one with the + // 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 - * one high and one low pulse. - */ + // Start at n = 2. We need to be able to set h/l so we have at least + // one high and one low pulse. for n in 2..64 { - /* Effectively, this does: - * pre = round((APB_CLK_FREQ / n) / frequency) - */ + // Effectively, this does: + // 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: - * h = round((duty_cycle * n) / 256) - */ + // Effectively, this does: + // h = round((duty_cycle * n) / 256) let mut h: i32 = (duty_cycle * n + 127) / 256; if h <= 0 { diff --git a/esp-wifi/src/ble/btdm.rs b/esp-wifi/src/ble/btdm.rs index 6d444c2d464..0997ce1a5b5 100644 --- a/esp-wifi/src/ble/btdm.rs +++ b/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 - * send packet to controller */ - notify_host_recv: extern "C" fn(*mut u8, u16) -> i32, /* callback used to notify that the - * controller has a packet to send to - * the host */ + // callback used to notify that the host can + // send packet to controller + notify_host_send_available: extern "C" fn(), + // callback used to notify that the + // controller has a packet to send to + // the host + notify_host_recv: extern "C" fn(*mut u8, u16) -> i32, } extern "C" { diff --git a/esp-wifi/src/ble/npl.rs b/esp-wifi/src/ble/npl.rs index f08516f95da..06c9d0a9fad 100644 --- a/esp-wifi/src/ble/npl.rs +++ b/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 i32>, /* ble_hci_trans_rx_cmd_fn */ + // ble_hci_trans_rx_cmd_fn + evt: Option i32>, evt_arg: *const c_void, - acl_cb: Option i32>, /* ble_hci_trans_rx_acl_fn */ + // ble_hci_trans_rx_acl_fn + acl_cb: Option i32>, acl_arg: *const c_void, );