Skip to content

Commit

Permalink
Prefer line comments // over block comments /* */ (#2738)
Browse files Browse the repository at this point in the history 
* Prefer line comments // over block comments /* */

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

* Mention in our API guideline that // should be prefered over /* */
  • Loading branch information
@JurajSadel
JurajSadel authored Dec 12, 2024
1 parent cc4e527 commit 3a03dd8
Show file tree
Hide file tree
Showing 6 changed files with 42 additions and 41 deletions.
1 change: 1 addition & 0 deletions documentation/API-GUIDELINES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion esp-hal/src/rtc_cntl/rtc/esp32c6.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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),
}
}
Expand Down
34 changes: 17 additions & 17 deletions esp-hal/src/rtc_cntl/sleep/esp32c6.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
28 changes: 12 additions & 16 deletions esp-hal/src/spi/master.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2516,28 +2516,25 @@ 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;
let mut bestpre: i32 = -1;
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;
Expand All @@ -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 {
Expand Down
12 changes: 7 additions & 5 deletions esp-wifi/src/ble/btdm.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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" {
Expand Down
6 changes: 4 additions & 2 deletions esp-wifi/src/ble/npl.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
);

Expand Down

0 comments on commit 3a03dd8

Please sign in to comment.