Merge pull request #249 from TheZoq2/doc_improvements

More documentation links

Author: therealprof

src/gpio.rs

@@ -2,13 +2,16 @@
 //!
 //! The GPIO pins are organised into groups of 16 pins which can be accessed through the
 //! `gpioa`, `gpiob`... modules. To get access to the pins, you first need to convert them into a
-//! HAL designed struct from the `pac` struct using the `spilit` function.
+//! HAL designed struct from the `pac` struct using the [split](trait.GpioExt.html#tymethod.split) function.
 //! ```rust
 //! // Acquire the GPIOC peripheral
 //! // NOTE: `dp` is the device peripherals from the `PAC` crate
 //! let mut gpioa = dp.GPIOA.split(&mut rcc.apb2);
 //! ```
 //!
+//! See the documentation for [rcc::APB2](../rcc/struct.APB2.html) for details about the input parameter to
+//! `split`.
+//!
 //! This gives you a struct containing two control registers `crl` and `crh`, and all the pins
 //! `px0..px15`. These structs are what you use to interract with the pins to change their modes,
 //! or their inputs or outputs. For example, to set `pa5` high, you would call

src/rcc.rs

@@ -36,6 +36,14 @@ impl RccExt for RCC {
 }
 
 /// Constrained RCC peripheral
+///
+/// Aquired by calling the [constrain](../trait.RccExt.html#tymethod.constrain) method
+/// on the Rcc struct from the `PAC`
+///
+/// ```rust
+/// let dp = pac::Peripherals::take().unwrap();
+/// let mut rcc = dp.RCC.constrain();
+/// ```
 pub struct Rcc {
     /// AMBA High-performance Bus (AHB) registers
     pub ahb: AHB,

src/rtc.rs

@@ -1,17 +1,6 @@
 /*!
   Real time clock
-
-  A continuously running clock that counts seconds. It is part of the backup domain which means
-  that the counter is not affected by system resets or standby mode. If Vbat is connected, it is
-  not reset even if the rest of the device is powered off. This allows it to be used to wake the
-  CPU when it is in low power mode.
-
-  Since it is part of the backup domain, write access to it must be enabled before the RTC can be
-  used. See `backup_domain` for more details.
-
-  See examples/rtc.rs and examples/blinky_rtc.rs for usage examples.
 */
-
 use crate::pac::{RCC, RTC};
 
 use crate::backup_domain::BackupDomain;
@@ -23,8 +12,22 @@ use core::convert::Infallible;
 const LSE_HERTZ: u32 = 32_768;
 
 /**
-  Interface to the real time clock
+  Real time clock
+
+  A continuously running clock that counts seconds¹. It is part of the backup domain which means
+  that the counter is not affected by system resets or standby mode. If Vbat is connected, it is
+  not reset even if the rest of the device is powered off. This allows it to be used to wake the
+  CPU when it is in low power mode.
+
+
+  See [examples/rtc.rs] and [examples/blinky_rtc.rs] for usage examples.
+
+  1: Unless configured to another frequency using [select_frequency](struct.Rtc.html#method.select_frequency)
+
+  [examples/rtc.rs]: https://github.com/stm32-rs/stm32f1xx-hal/blob/v0.6.1/examples/rtc.rs
+  [examples/blinky_rtc.rs]: https://github.com/stm32-rs/stm32f1xx-hal/blob/v0.6.1/examples/blinky_rtc.rs
 */
+
 pub struct Rtc {
     regs: RTC,
 }
@@ -33,6 +36,12 @@ impl Rtc {
     /**
       Initialises the RTC. The `BackupDomain` struct is created by
       `Rcc.bkp.constrain()`.
+
+      The frequency is set to 1 Hz.
+
+      Since the RTC is part of the backup domain, The RTC counter is not reset by normal resets or
+      power cycles where (VBAT) still has power. Use [set_time](#method.set_time) if you want to
+      reset the counter.
     */
     pub fn rtc(regs: RTC, bkp: &mut BackupDomain) -> Self {
         let mut result = Rtc { regs };
@@ -123,15 +132,17 @@ impl Rtc {
         self.clear_alarm_flag();
     }
 
-    /// Enables the RTCALARM interrupt
+    /// Enables the RTC interrupt to trigger when the counter reaches the alarm value. In addition,
+    /// if the EXTI controller has been set up correctly, this function also enables the RTCALARM
+    /// interrupt.
     pub fn listen_alarm(&mut self) {
         // Enable alarm interrupt
         self.perform_write(|s| {
             s.regs.crh.modify(|_, w| w.alrie().set_bit());
         })
     }
 
-    /// Disables the RTCALARM interrupt
+    /// Stops the RTC alarm from triggering the RTC and RTCALARM interrupts
     pub fn unlisten_alarm(&mut self) {
         // Disable alarm interrupt
         self.perform_write(|s| {
@@ -147,7 +158,7 @@ impl Rtc {
         self.regs.cnth.read().bits() << 16 | self.regs.cntl.read().bits()
     }
 
-    /// Enables the RTC second interrupt
+    /// Enables triggering the RTC interrupt every time the RTC counter is increased
     pub fn listen_seconds(&mut self) {
         self.perform_write(|s| s.regs.crh.modify(|_, w| w.secie().set_bit()))
     }