gpio, spi and i2c::master cleanup, smaller updates
#3010
Conversation
esp-hal/src/gpio/mod.rs
Outdated
| /// ```rust, no_run | ||
| #[doc = crate::before_snippet!()] | ||
| /// # use esp_hal::gpio::Io; | ||
| /// let mut io = Io::new(peripherals.IO_MUX); |
There was a problem hiding this comment.
Oh come on, do we really need this?
There was a problem hiding this comment.
Meeh, no, but I can purely imagine someone struggling with something like "which peripheral should I put there" or such stuff 😆
I know, it hurts to see such simple things there, but I think it doesn't hurt us to have even such things with examples to avoid a potential handful of questions like the one I wrote above
There was a problem hiding this comment.
I know, it hurts to see such simple things there, but I think it doesn't hurt us to have even such things with examples to avoid a potential handful of questions like the one I wrote above
I understand the sentiment here, but I think we should try and let rustdoc do the heavy lifting for us here, https://docs.esp-rs.org/esp-hal/esp-hal/0.23.1/esp32c6/esp_hal/gpio/struct.Io.html gives a clickable link to the IO_MUX type, which shows where it comes from. If we follow this practice on every API item we're going to have more doc comments than code I think.
Would you mind removing this one?
playfulFence
force-pushed
the
docs/contributing
branch
from
3733c9b to
5c86c0c
Compare
playfulFence
changed the title
gpio and i2c::master cleanup, smaller updatesgpio, spi and i2c::master cleanup, smaller updates
esp-hal/src/gpio/mod.rs
Outdated
| @@ -1319,8 +1353,9 @@ impl<'d> Input<'d> { | |||
| /// otherwise your program will be stuck in a loop as long as the pin is | |||
| /// reading the corresponding level. | |||
| /// | |||
| /// ## Example: print something when a button is pressed. | |||
| /// ## Example | |||
There was a problem hiding this comment.
If you're splitting out the title into a subsection, call this Examples
There was a problem hiding this comment.
There's only one example, so # Examples wouldn't be suitable here (? 🤷🏼 ). I just made it follow the “format” that is used everywhere in the driver.
There was a problem hiding this comment.
Or, actually, we can just replace every occurrence of # Example with # Examples to be more consistent
playfulFence
force-pushed
the
docs/contributing
branch
from
a559080 to
3c1236a
Compare
esp-hal/src/gpio/mod.rs
Outdated
| /// ```rust, no_run | ||
| #[doc = crate::before_snippet!()] | ||
| /// # use esp_hal::gpio::Io; | ||
| /// let mut io = Io::new(peripherals.IO_MUX); |
There was a problem hiding this comment.
I know, it hurts to see such simple things there, but I think it doesn't hurt us to have even such things with examples to avoid a potential handful of questions like the one I wrote above
I understand the sentiment here, but I think we should try and let rustdoc do the heavy lifting for us here, https://docs.esp-rs.org/esp-hal/esp-hal/0.23.1/esp32c6/esp_hal/gpio/struct.Io.html gives a clickable link to the IO_MUX type, which shows where it comes from. If we follow this practice on every API item we're going to have more doc comments than code I think.
Would you mind removing this one?
| @@ -1426,6 +1470,14 @@ impl<'d> Input<'d> { | |||
| /// | |||
| /// The output signal can be passed to peripherals in place of an output | |||
| /// pin. | |||
| /// ```rust, no_run | |||
There was a problem hiding this comment.
I'm not so sure about these GPIO doc comments, they seem to, on some level repeat themselves. Perhaps we should just document split, and leave the rest? Or maybe we can reference split in the other API items.
Not that stress about this at the moment though, as these are unstable APIs :)
playfulFence
force-pushed
the
docs/contributing
branch
from
3c1236a to
f57158e
Compare
closes #2999 and does some progress towards #2623