Merge pull request #233 from braun-embedded/documentation

Update some documentation

Author: hannobraun

src/gpio.rs

@@ -4,7 +4,9 @@
 //! peripheral, and is required to convert instances of [`Pin`] to a
 //! [`GpioPin`], which provides the core GPIO API.
 //!
-//! The GPIO peripheral is described in the user manual, chapter 9.
+//! The GPIO peripheral is described in the following user manuals:
+//! - LPC82x user manual, chapter 9
+//! - LPC84x user manual, chapter 12
 //!
 //! # Examples
 //!
@@ -177,6 +179,23 @@ impl GPIO<init_state::Enabled> {
 }
 
 /// A pin used for general purpose I/O (GPIO)
+///
+/// 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`]
+///
+/// [`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
 pub struct GpioPin<T, D> {
     token: pins::Token<T, init_state::Enabled>,
     _direction: D,

src/lib.rs

@@ -60,6 +60,7 @@
 //! [`Peripherals`], which is the entry point to the whole API.
 //!
 //! [`Cargo.toml`]: https://github.com/lpc-rs/lpc8xx-hal/blob/master/Cargo.toml
+//! [`Peripherals`]: struct.Peripherals.html
 //!
 //!
 //! ## Examples
@@ -201,6 +202,9 @@ use embedded_hal as hal;
 /// make sure you know what you're doing. In specific terms, this means you
 /// should be fully aware of what your code does, and whether that is a valid
 /// use of the hardware.
+///
+/// [`Peripherals::take`]: #method.take
+/// [`Peripherals::steal`]: #method.steal
 #[allow(non_snake_case)]
 pub struct Peripherals {
     /// Pins that can be used for GPIO or other functions

src/pins.rs

@@ -1,4 +1,9 @@
 //! API to control pins
+//!
+//! The most important part of this API is [`Pin`]. Please refer to its
+//! documentation, to learn how to use this module.
+//!
+//! [`Pin`]: struct.Pin.html
 
 mod gen;
 mod pin;

src/pins/gen.rs

@@ -14,12 +14,17 @@ macro_rules! pins {
     )*) => {
         /// Provides access to all pins
         ///
+        /// You can get access to an instance of this struct through
+        ///[`Peripherals`].
+        ///
         /// # Limitations
         ///
         /// This struct currently provides access to all pins that can be
         /// available on an LPC8xx part. Please make sure that you are aware of
         /// which pins are actually available on your specific part, and only
         /// use those.
+        ///
+        /// [`Peripherals`]: ../struct.Peripherals.html
         #[allow(missing_docs)]
         pub struct Pins {
             $(pub $field: Pin<$type, $default_state_ty>,)*
@@ -42,9 +47,10 @@ macro_rules! pins {
         $(
             /// Identifies a specific pin
             ///
-            /// Pins can be accessed via the field `pins` of [`swm::Parts`].
+            /// This type is used as a type parameter on [`Pin`]. Check out
+            /// [`Pin`]'s documentation for more information.
             ///
-            /// [`swm::Parts`]: ../swm/struct.Parts.html
+            /// [`Pin`]: struct.Pin.html
             #[allow(non_camel_case_types)]
             pub struct $type(());
 

src/pins/pin.rs

@@ -12,25 +12,26 @@ use super::{
 /// Main API for controlling pins
 ///
 /// `Pin` has two type parameters:
-/// - `T`, to indicate which specific pin this instance of `Pin` represents (so,
-///   [`PIO0_0`], [`PIO0_1`], and so on)
-/// - `S`, to indicate which state the represented pin is currently in
+/// - `T`, to indicate which specific pin this instance of `Pin` represents
+///   ([`PIO0_0`], [`PIO0_1`], and so on).
+/// - `S`, to indicate which state the represented pin is currently in.
 ///
 /// A pin instance can be in one of the following states:
-/// - [`state::Unused`], to indicate that the pin is currently not used
-/// - [`state::Gpio`], to indicate that the pin is being used for
-///   general-purpose I/O
+/// - [`state::Unused`], to indicate that the pin is currently not used.
 /// - [`state::Swm`], to indicate that the pin is available for switch
-///   matrix function assignment
+///   matrix function assignment.
 /// - [`state::Analog`], to indicate that the pin is being used for analog
-///   input
+///   input.
+///
+/// A pin that is in the GPIO state is represented by its own struct,
+/// [`GpioPin`].
 ///
 /// # State Management
 ///
 /// All pins start out in their initial state, as defined in the user manual. To
-/// prevent us from making mistakes, only the methods that induce a valid state
-/// transition are available. Code that tries to call a method that would cause
-/// an invalid state transition will simply not compile:
+/// prevent the user from making a mistake, only the methods that induce a valid
+/// state transition are available. Code that tries to call a method that would
+/// cause an invalid state transition will simply not compile:
 ///
 /// ``` no_run
 /// # use lpc8xx_hal::Peripherals;
@@ -51,10 +52,10 @@ use super::{
 ///     &mut swm_handle,
 /// );
 ///
-/// // As long as the function is assigned, we can't use the pin for
-/// // general-purpose I/O. Therefore the following method call would cause a
-/// // compile-time error.
-/// // let pio0_12 = pio0_12.into_gpio_pin(&p.GPIO);
+/// // As long as a function is assigned, we can't use the pin for general-
+/// // purpose I/O. Therefore the following method call would cause a compile-
+/// // time error.
+/// // let pio0_12 = pio0_12.into_input_pin(&p.GPIO);
 /// ```
 ///
 /// To use the pin in the above example for GPIO, we first have to unassign the
@@ -78,10 +79,10 @@ use super::{
 /// #     &mut swm_handle,
 /// # );
 /// #
-/// #[cfg(feature = "82x")]
-/// let gpio = p.GPIO;
-/// #[cfg(feature = "845")]
-/// let gpio = p.GPIO.enable(&mut syscon.handle);
+/// # #[cfg(feature = "82x")]
+/// # let gpio = p.GPIO;
+/// # #[cfg(feature = "845")]
+/// # let gpio = p.GPIO.enable(&mut syscon.handle);
 ///
 /// let (clkout, pio0_12) = clkout.unassign(pio0_12, &mut swm_handle);
 /// let pio0_12 = pio0_12.into_unused_pin();
@@ -116,7 +117,7 @@ use super::{
 /// let pin = p.pins.pio0_12
 ///     .into_swm_pin();
 ///
-/// // Functions can be assigned now using the methods on `Function`
+/// // Functions can be assigned now using the SWM API
 /// ```
 ///
 /// As mentioned above, a function can be fixed or movable. But there is also
@@ -132,7 +133,7 @@ use super::{
 /// topic, [please help us figure this out](https://github.com/lpc-rs/lpc8xx-hal/issues/44).
 ///
 /// Once a pin is in the SWM state, you can assign functions to it. Please refer
-/// to [`Function`] for more information on how to do that.
+/// to the [SWM API] for more information on how to do that.
 ///
 /// # Analog Input
 ///
@@ -151,7 +152,7 @@ use super::{
 /// #[cfg(feature = "845")]
 /// let mut swm_handle = swm.handle.enable(&mut syscon.handle);
 ///
-/// // Transition pin into ADC state
+/// // Transition pin to ADC state
 /// let (adc_2, pio0_14) = swm.fixed_functions.adc_2.assign(
 ///     p.pins.pio0_14.into_swm_pin(),
 ///     &mut swm_handle,
@@ -168,8 +169,7 @@ use super::{
 /// [`Pin::into_output_pin`]: struct.Pin.html#method.into_output_pin
 /// [`GpioPin`]: ../gpio/struct.GpioPin.html
 /// [`Pin::into_swm_pin`]: struct.Pin.html#method.into_swm_pin
-/// [`lpc82x::IOCON`]: https://docs.rs/lpc82x-pac/0.7.*/lpc82x_pac/struct.IOCON.html
-/// [`lpc82x::ADC`]: https://docs.rs/lpc82x-pac/0.7.*/lpc82x_pac/struct.ADC.html
+/// [SWM API]: ../swm/index.html
 pub struct Pin<T: Trait, S: State> {
     pub(crate) ty: T,
     pub(crate) _state: S,
@@ -180,6 +180,22 @@ where
     T: Trait,
 {
     /// Transition pin to GPIO input mode
+    ///
+    /// This method is only available while the pin is in the unused state. Code
+    /// that attempts to call this method while the pin is in any other state
+    /// will not compile. See [State Management] for more information on
+    /// managing pin states.
+    ///
+    /// Consumes this `Pin` instance and returns an instance of [`GpioPin`],
+    /// which provides access to all GPIO functions.
+    ///
+    /// This method requires a GPIO token from the [`GPIO`] struct, to ensure
+    /// that the GPIO peripheral is enabled, and stays enabled while the pin is
+    /// in the GPIO mode.
+    ///
+    /// [State Management]: #state-management
+    /// [`GpioPin`]: ../gpio/struct.GpioPin.html
+    /// [`GPIO`]: ../gpio/struct.GPIO.html
     pub fn into_input_pin(
         self,
         token: Token<T, init_state::Enabled>,
@@ -188,6 +204,22 @@ where
     }
 
     /// Transition pin to GPIO output mode
+    ///
+    /// This method is only available while the pin is in the unused state. Code
+    /// that attempts to call this method while the pin is in any other state
+    /// will not compile. See [State Management] for more information on
+    /// managing pin states.
+    ///
+    /// Consumes this `Pin` instance and returns an instance of [`GpioPin`],
+    /// which provides access to all GPIO functions.
+    ///
+    /// This method requires a GPIO token from the [`GPIO`] struct, to ensure
+    /// that the GPIO peripheral is enabled, and stays enabled while the pin is
+    /// in the GPIO mode.
+    ///
+    /// [State Management]: #state-management
+    /// [`GpioPin`]: ../gpio/struct.GpioPin.html
+    /// [`GPIO`]: ../gpio/struct.GPIO.html
     pub fn into_output_pin(
         self,
         token: Token<T, init_state::Enabled>,
@@ -196,7 +228,7 @@ where
         GpioPin::new(token, initial)
     }
 
-    /// Transition pin to SWM state
+    /// Transition pin to SWM mode
     ///
     /// This method is only available while the pin is in the unused state. Code
     /// that attempts to call this method while the pin is in any other state
@@ -206,7 +238,8 @@ where
     /// Consumes this pin instance and returns a new instance that is in the SWM
     /// state, making this pin available for switch matrix function assignment.
     ///
-    /// Please refer [`Function`] to learn more about SWM function assignment.
+    /// Please refer to the [SWM API] to learn more about SWM function
+    /// assignment.
     ///
     /// # Example
     ///
@@ -222,6 +255,7 @@ where
     /// ```
     ///
     /// [State Management]: #state-management
+    /// [SWM API]: ../swm/index.html
     pub fn into_swm_pin(self) -> Pin<T, state::Swm<(), ()>> {
         Pin {
             ty: self.ty,

src/pins/state.rs

@@ -42,13 +42,13 @@ impl State for Analog {}
 /// functions have been assigned to a pin:
 ///
 /// - `Output` tracks whether an output function has been assigned. Zero or
-///   one output functions can be assigned to a pin.
+///   one output functions can be assigned to a pin at a time.
 /// - `Inputs` tracks the number of assigned input functions. Any number of
 ///   input functions can be assigned to a pin at the same time.
 ///
 /// Both type parameters use nested tuples to count the number of assigned
-/// functions. The empty tuple (`()`) represents zero assigned functions,
-/// the empty tuple nested in another tuple (`((),)`) represents one
+/// functions. The empty tuple, `()`, represents zero assigned functions,
+/// the empty tuple nested in another tuple, `((),)`, represents one
 /// function being assigned, `(((),))` represents two assigned functions,
 /// and so forth. This is a bit of a hack, of course, but it should do until
 /// [const generics] become available.

src/swm.rs

@@ -3,7 +3,11 @@
 //! The entry point to this API is [`SWM`]. Please refer to [`SWM`]'s
 //! documentation for additional information.
 //!
-//! The switch matrix is described in the user manual, chapter 7.
+//! The switch matrix is described in the following user manuals:
+//! - LPC82x user manual, chapter 7
+//! - LPC84x user manual, chapter 10
+//!
+//! [`SWM`]: struct.SWM.html
 
 pub mod state;
 
@@ -17,8 +21,9 @@ mod peripheral;
 
 pub use self::{
     fixed_functions::*,
+    function_kind::{Analog, FunctionKind, Input, Output},
     functions::{Function, FunctionTrait},
     handle::Handle,
     movable_functions::*,
-    peripheral::SWM,
+    peripheral::{Parts, SWM},
 };

src/swm/fixed_functions.rs

@@ -38,10 +38,9 @@ macro_rules! fixed_functions {
         $(
             /// Represents a fixed function
             ///
-            /// Fixed functions can be accessed via the field `fixed_functions`
-            /// of [`swm::Parts`].
+            /// Fixed functions can be accessed through [`FixedFunctions`].
             ///
-            /// [`swm::Parts`]: struct.Parts.html
+            /// [`FixedFunctions`]: struct.FixedFunctions.html
             #[allow(non_camel_case_types)]
             pub struct $type(());
 

src/swm/functions.rs

@@ -14,6 +14,13 @@ use super::{
 /// The type parameter `T` identifies the fixed or movable function that an
 /// instance of `Function` controls. The other type paramter, `State`, tracks
 /// whether this function is assigned to a pin, and which pin it is assigned to.
+///
+/// You can gain access to the instances of this struct that represent fixed
+/// functions through [`FixedFunctions`], to those that represent movable
+/// functions through [`MovableFunctions`].
+///
+/// [`FixedFunctions`]: struct.FixedFunctions.html
+/// [`MovableFunctions`]: struct.MovableFunctions.html
 pub struct Function<T, S> {
     ty: T,
     _state: S,
@@ -41,7 +48,7 @@ impl<T> Function<T, Unassigned> {
     ///   documentation on [`Pin`] for information on pin state management.
     /// - The function must be assignable to the pin. Movable functions can be
     ///   assigned to any pin, but fixed functions can be assigned to only one
-    ///   pin.
+    ///   specific pin.
     /// - The state of the pin must allow another function of this type to be
     ///   assigned. Input functions can always be assigned, but only one output
     ///   or bidirectional function can be assigned to a given pin at any time.
@@ -86,6 +93,8 @@ impl<T> Function<T, Unassigned> {
     /// ```
     ///
     /// [`Unassigned`]: state/struct.Unassigned.html
+    /// [`Pin`]: ../pins/struct.Pin.html
+    /// [`pins::state::Swm`]: ../pins/state/struct.Swm.html
     pub fn assign<P, S>(
         mut self,
         mut pin: Pin<P, S>,
@@ -164,6 +173,8 @@ impl<T, P> Function<T, Assigned<P>> {
     /// ```
     ///
     /// [`Assigned`]: state/struct.Assigned.html
+    /// [`Pin`]: ../pins/struct.Pin.html
+    /// [`pins::state::Swm`]: ../pins/state/struct.Swm.html
     pub fn unassign<S>(
         mut self,
         mut pin: Pin<P, S>,
@@ -197,6 +208,9 @@ impl<T, P> Function<T, Assigned<P>> {
 ///
 /// Please refer [`Function::assign`] and [`Function::unassign`] for the public
 /// API that uses this trait.
+///
+/// [`Function::assign`]: struct.Function.html#method.assign
+/// [`Function::unassign`]: struct.Function.html#method.unassign
 pub trait FunctionTrait<P: pins::Trait> {
     /// Whether this is an input or output function
     ///