Improve & unify documentation for implemented embededd-hal traits

As proposed in
lpc-rs#233 (comment)

Author: david-sawatzke

src/adc.rs

@@ -49,8 +49,12 @@ use crate::{
 ///
 /// Please refer to the [module documentation] for more information.
 ///
+/// # `embedded-hal` traits
+/// - [`embedded_hal::adc::OneShot`] for measuring the voltage on a pin
+///
 /// [`Peripherals`]: ../struct.Peripherals.html
 /// [module documentation]: index.html
+/// [`embedded_hal::adc::OneShot`]: #impl-OneShot%3CADC%3CEnabled%3C()%3E%3E%2C%20u16%2C%20PIN%3E
 pub struct ADC<State = init_state::Enabled> {
     adc: pac::ADC0,
     _state: State,
@@ -153,6 +157,7 @@ where
 {
     type Error = ();
 
+    /// Request that the ADC begin a conversion on the specified pin
     fn read(&mut self, _: &mut PIN) -> nb::Result<u16, Self::Error> {
         // Start the measurement of the given channel
         // Follows the description in the um

src/ctimer.rs

@@ -81,6 +81,11 @@ pub struct DetachedPwmPin<CTOutput> {
 }
 
 /// Represents a pwm channel assigned to an output pin
+///
+/// # `embedded-hal` traits
+/// - [`embedded_hal::PwmPin`]
+///
+/// [`embedded_hal::PwmPin`]: #impl-PwmPin
 pub struct CTimerPwmPin {
     mr: RegProxy<MR>,
     msr: RegProxy<MSR>,
@@ -195,14 +200,17 @@ impl PwmPin for CTimerPwmPin {
     // and would involve a hidden `CriticalSection`
     fn disable(&mut self) {}
 
+    /// Returns the current duty cycle
     fn get_duty(&self) -> Self::Duty {
         self.msr[self.number as usize].read().match_shadow().bits()
     }
 
+    /// Returns the maximum duty cycle value
     fn get_max_duty(&self) -> Self::Duty {
         self.mr[3].read().match_().bits()
     }
 
+    /// Sets a new duty cycle
     fn set_duty(&mut self, duty: Self::Duty) {
         unsafe {
             self.msr[self.number as usize]

src/delay.rs

@@ -29,6 +29,13 @@ const SYSTICK_RANGE: u32 = 0x0100_0000;
 const SYSTEM_CLOCK: u32 = 12_000_000;
 
 /// System timer (SysTick) as a delay provider
+///
+/// # `embedded-hal` traits
+/// - [`embedded_hal::blocking::delay::DelayUs`]
+/// - [`embedded_hal::blocking::delay::DelayMs`]
+///
+/// [`embedded_hal::blocking::delay::DelayUs`]: #impl-DelayUs%3Cu32%3E
+/// [`embedded_hal::blocking::delay::DelayMs`]: #impl-DelayMs%3Cu32%3E
 #[derive(Clone)]
 pub struct Delay {
     scale: u32,
@@ -52,6 +59,7 @@ impl Delay {
 }
 
 impl DelayMs<u32> for Delay {
+    /// Pauses execution for `ms` milliseconds
     // At 30 MHz (the maximum frequency), calling delay_us with ms * 1_000 directly overflows at 0x418937 (over the max u16 value)
     // So we implement a separate, higher level, delay loop
     fn delay_ms(&mut self, mut ms: u32) {
@@ -65,6 +73,7 @@ impl DelayMs<u32> for Delay {
 }
 
 impl DelayMs<u16> for Delay {
+    /// Pauses execution for `ms` milliseconds
     fn delay_ms(&mut self, ms: u16) {
         // Call delay_us directly, since we don't have to use the additional
         // delay loop the u32 variant uses
@@ -73,13 +82,15 @@ impl DelayMs<u16> for Delay {
 }
 
 impl DelayMs<u8> for Delay {
+    /// Pauses execution for `ms` milliseconds
     fn delay_ms(&mut self, ms: u8) {
         self.delay_ms(ms as u16);
     }
 }
 
 // At 30MHz (the maximum frequency), this overflows at approx. 2^32 / 30 = 146 seconds
 impl DelayUs<u32> for Delay {
+    /// Pauses execution for `us` milliseconds
     fn delay_us(&mut self, us: u32) {
         // The SysTick Reload Value register supports values between 1 and 0x00FFFFFF.
         // Here half the maximum is used so we have some play if there's a long running interrupt.
@@ -108,12 +119,14 @@ impl DelayUs<u32> for Delay {
 }
 
 impl DelayUs<u16> for Delay {
+    /// Pauses execution for `us` milliseconds
     fn delay_us(&mut self, us: u16) {
         self.delay_us(us as u32)
     }
 }
 
 impl DelayUs<u8> for Delay {
+    /// Pauses execution for `us` milliseconds
     fn delay_us(&mut self, us: u8) {
         self.delay_us(us as u32)
     }

src/gpio.rs

@@ -183,19 +183,20 @@ impl GPIO<init_state::Enabled> {
 /// You can get access to an instance of this struct by switching a pin to the
 /// GPIO state, using [`Pin::into_input_pin`] or [`Pin::into_output_pin`].
 ///
-/// While in input mode, this struct implements the [`InputPin`] trait.
-///
-/// While in output mode, this struct implements the following traits:
-/// - [`OutputPin`]
-/// - [`StatefulOutputPin`]
-/// - [`ToggleableOutputPin`]
+/// # `embedded-hal` traits
+/// - While in input mode
+///   - [`embedded_hal::digital::v2::InputPin`] for reading the pin state
+/// - While in output mode
+///   - [`embedded_hal::digital::v2::OutputPin`] for setting the pin state
+///   - [`embedded_hal::digital::v2::StatefulOutputPin`] for reading the pin output state
+///   - [`embedded_hal::digital::v2::ToggleableOutputPin`] for toggling the pin state
 ///
 /// [`Pin::into_input_pin`]: ../pins/struct.Pin.html#method.into_input_pin
 /// [`Pin::into_output_pin`]: ../pins/struct.Pin.html#method.into_output_pin
-/// [`InputPin`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/digital/v2/trait.InputPin.html
-/// [`OutputPin`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/digital/v2/trait.OutputPin.html
-/// [`StatefulOutputPin`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/digital/v2/trait.StatefulOutputPin.html
-/// [`ToggleableOutputPin`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/digital/v2/trait.ToggleableOutputPin.html
+/// [`embedded_hal::digital::v2::InputPin`]: #impl-InputPin
+/// [`embedded_hal::digital::v2::OutputPin`]: #impl-OutputPin
+/// [`embedded_hal::digital::v2::StatefulOutputPin`]: #impl-StatefulOutputPin
+/// [`embedded_hal::digital::v2::ToggleableOutputPin`]: #impl-ToggleableOutputPin
 pub struct GpioPin<T, D> {
     token: pins::Token<T, init_state::Enabled>,
     _direction: D,

src/i2c.rs

@@ -81,6 +81,12 @@ use crate::{
 /// Additional limitations are documented on the specific methods that they
 /// apply to.
 ///
+/// # `embedded-hal` traits
+/// - [`embedded_hal::blocking::i2c::Read`] for synchronous reading
+/// - [`embedded_hal::blocking::i2c::Write`] for synchronous writing
+///
+/// [`embedded_hal::blocking::i2c::Read`]: #impl-Read
+/// [`embedded_hal::blocking::i2c::Write`]: #impl-Write
 /// [module documentation]: index.html
 pub struct I2C<I, State = init_state::Enabled> {
     i2c: I,

src/mrt.rs

@@ -59,6 +59,11 @@ impl MRT {
 pub const MAX_VALUE: u32 = 0x7fff_ffff - 1;
 
 /// Represents a MRT0 channel
+///
+/// # `embedded-hal` traits
+/// - [`embedded_hal::timer::CountDown`]
+///
+/// [`embedded_hal::timer::CountDown`]: #impl-CountDown
 pub struct Channel<T: Reg>(RegProxy<T>);
 
 impl<T> Channel<T>
@@ -109,6 +114,7 @@ where
             .write(|w| unsafe { w.ivalue().bits(reload + 1) });
     }
 
+    /// Non-blockingly "waits" until the count down finishes
     fn wait(&mut self) -> Result<(), Void> {
         if self.0.stat.read().intflag().is_pending_interrupt() {
             // Reset the interrupt flag

src/spi.rs

@@ -75,8 +75,17 @@ use crate::{
 ///
 /// Please refer to the [module documentation] for more information.
 ///
+/// # `embedded-hal` traits
+///
+/// - [`embedded_hal::spi::FullDuplex`] for asynchronous transfers
+/// - [`embedded_hal::blocking::spi::Transfer`] for synchronous transfers
+/// - [`embedded_hal::blocking::spi::Write`] for synchronous writes
+///
 /// [`Peripherals`]: ../struct.Peripherals.html
 /// [module documentation]: index.html
+/// [`embedded_hal::spi::FullDuplex`]: #impl-FullDuplex%3Cu8%3E
+/// [`embedded_hal::blocking::spi::Transfer`]: #impl-Transfer%3CW%3E
+/// [`embedded_hal::blocking::spi::Write`]: #impl-Write%3CW%3E
 pub struct SPI<I, State = init_state::Enabled> {
     spi: I,
     _state: State,

src/usart/peripheral.rs

@@ -30,18 +30,19 @@ use super::{
 /// same place, or you can move the `rx` and `tx` fields out of this struct, to
 /// use the sender and receiver from different contexts.
 ///
-/// This struct implement the following traits:
-/// - [`embedded_hal::serial::Read`]
-/// - [`embedded_hal::serial::Write`]
-/// - [`embedded_hal::blocking::serial::Write`]
-///
 /// Please refer to the [module documentation] for more information.
 ///
+/// # `embedded-hal` traits
+/// - [`embedded_hal::serial::Read`] for asynchronous receiving
+/// - [`embedded_hal::serial::Write`] for asynchronous sending
+/// - [`embedded_hal::blocking::serial::Write`] for synchronous sending
+///
+///
 /// [`Peripherals`]: ../struct.Peripherals.html
-/// [`embedded_hal::serial::Read`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/serial/trait.Read.html
-/// [`embedded_hal::serial::Write`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/serial/trait.Write.html
-/// [`embedded_hal::blocking::serial::Write`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/blocking/serial/trait.Write.html
 /// [module documentation]: index.html
+/// [`embedded_hal::serial::Read`]: #impl-Read%3Cu8%3E
+/// [`embedded_hal::serial::Write`]: #impl-Write%3Cu8%3E
+/// [`embedded_hal::blocking::serial::Write`]: #impl-Write
 pub struct USART<I, State = init_state::Enabled> {
     /// The USART Receiver
     pub rx: Rx<I, State>,
@@ -267,6 +268,7 @@ where
 {
     type Error = Error;
 
+    /// Reads a single word from the serial interface
     fn read(&mut self) -> nb::Result<u8, Self::Error> {
         self.rx.read()
     }
@@ -278,10 +280,12 @@ where
 {
     type Error = Void;
 
+    /// Writes a single word to the serial interface
     fn write(&mut self, word: u8) -> nb::Result<(), Self::Error> {
         self.tx.write(word)
     }
 
+    /// Ensures that none of the previously written words are still buffered
     fn flush(&mut self) -> nb::Result<(), Self::Error> {
         self.tx.flush()
     }
@@ -297,6 +301,7 @@ where
     Self: BlockingWriteDefault<u8>,
     I: Instance,
 {
+    /// Writes a string slice into this writer, returning whether the write succeeded.
     fn write_str(&mut self, s: &str) -> fmt::Result {
         self.tx.write_str(s)
     }

src/usart/rx.rs

@@ -6,9 +6,11 @@ use super::instances::Instance;
 
 /// USART receiver
 ///
-/// This struct implements the [`embedded_hal::serial::Read`] trait.
+/// # `embedded-hal` traits
+/// - [`embedded_hal::serial::Read`] for asynchronous receiving
 ///
-/// [`embedded_hal::serial::Read`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/serial/trait.Read.html
+///
+/// [`embedded_hal::serial::Read`]: #impl-Read%3Cu8%3E
 pub struct Rx<I, State = init_state::Enabled> {
     _instance: PhantomData<I>,
     _state: PhantomData<State>,

src/usart/tx.rs

@@ -12,12 +12,12 @@ use super::instances::Instance;
 
 /// USART transmitter
 ///
-/// This struct implements the following traits:
-/// - [`embedded_hal::serial::Write`]
-/// - [`embedded_hal::blocking::serial::Write`]
+/// # `embedded-hal` traits
+/// - [`embedded_hal::serial::Write`] for asynchronous sending
+/// - [`embedded_hal::blocking::serial::Write`] for synchronous receiving
 ///
-/// [`embedded_hal::serial::Write`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/serial/trait.Write.html
-/// [`embedded_hal::blocking::serial::Write`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/blocking/serial/trait.Write.html
+/// [`embedded_hal::serial::Write`]: #impl-Write%3Cu8%3E
+/// [`embedded_hal::blocking::serial::Write`]: #impl-Write
 pub struct Tx<I, State = init_state::Enabled> {
     _instance: PhantomData<I>,
     _state: PhantomData<State>,