diff --git a/src/gpio.rs b/src/gpio.rs index 228fcb968..c7c4dda0a 100644 --- a/src/gpio.rs +++ b/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 { } /// 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 { token: pins::Token, _direction: D, diff --git a/src/lib.rs b/src/lib.rs index 65129ab7d..8928cb83d 100644 --- a/src/lib.rs +++ b/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 diff --git a/src/pins.rs b/src/pins.rs index 7e777a8a7..52122f694 100644 --- a/src/pins.rs +++ b/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; diff --git a/src/pins/gen.rs b/src/pins/gen.rs index d263073e2..178d68d5f 100644 --- a/src/pins/gen.rs +++ b/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(()); diff --git a/src/pins/pin.rs b/src/pins/pin.rs index 82992327c..3f5c6a8f3 100644 --- a/src/pins/pin.rs +++ b/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 { 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, @@ -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, @@ -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> { Pin { ty: self.ty, diff --git a/src/pins/state.rs b/src/pins/state.rs index f9fb5a9fa..8079fb38c 100644 --- a/src/pins/state.rs +++ b/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. diff --git a/src/swm.rs b/src/swm.rs index ae22f504b..1b8f8ae94 100644 --- a/src/swm.rs +++ b/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}, }; diff --git a/src/swm/fixed_functions.rs b/src/swm/fixed_functions.rs index f9012056a..189f4379f 100644 --- a/src/swm/fixed_functions.rs +++ b/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(()); diff --git a/src/swm/functions.rs b/src/swm/functions.rs index b443bd24d..215f9271c 100644 --- a/src/swm/functions.rs +++ b/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 { ty: T, _state: S, @@ -41,7 +48,7 @@ impl Function { /// 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 Function { /// ``` /// /// [`Unassigned`]: state/struct.Unassigned.html + /// [`Pin`]: ../pins/struct.Pin.html + /// [`pins::state::Swm`]: ../pins/state/struct.Swm.html pub fn assign( mut self, mut pin: Pin, @@ -164,6 +173,8 @@ impl Function> { /// ``` /// /// [`Assigned`]: state/struct.Assigned.html + /// [`Pin`]: ../pins/struct.Pin.html + /// [`pins::state::Swm`]: ../pins/state/struct.Swm.html pub fn unassign( mut self, mut pin: Pin, @@ -197,6 +208,9 @@ impl Function> { /// /// 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 { /// Whether this is an input or output function /// diff --git a/src/swm/handle.rs b/src/swm/handle.rs index 9a19aa298..bced43f68 100644 --- a/src/swm/handle.rs +++ b/src/swm/handle.rs @@ -5,12 +5,15 @@ use crate::{init_state, pac, syscon}; /// Handle to the SWM peripheral /// /// Can be used to enable and disable the switch matrix. It is also required by -/// other parts of the API to synchronize access the the underlying registers, -/// wherever this is required. +/// other parts of the HAL API to synchronize access the the underlying +/// registers, wherever this is required. +/// +/// This struct is part of [`swm::Parts`]. /// /// Please refer to the [module documentation] for more information about the /// PMU. /// +/// [`swm::Parts`]: struct.Parts.html /// [module documentation]: index.html pub struct Handle { pub(super) swm: pac::SWM0, @@ -29,12 +32,12 @@ impl Handle { impl Handle { /// Enable the switch matrix /// - /// This method is only available, if `SWM` is in the [`Disabled`] state. - /// Code that attempts to call this method when the peripheral is already - /// enabled will not compile. + /// This method is only available, if `swm::Handle` is in the [`Disabled`] + /// state. Code that attempts to call this method when the peripheral is + /// already enabled will not compile. /// - /// Consumes this instance of `SWM` and returns another instance that has - /// its `State` type parameter set to [`Enabled`]. + /// Consumes this instance of `swm::Handle` and returns another instance + /// that has its `State` type parameter set to [`Enabled`]. /// /// [`Disabled`]: ../init_state/struct.Disabled.html /// [`Enabled`]: ../init_state/struct.Enabled.html @@ -57,12 +60,12 @@ impl Handle { /// The switch matrix retains it's configuration while disabled, but /// doesn't allow modifications /// - /// This method is only available, if `SWM` is in the [`Enabled`] state. - /// Code that attempts to call this method when the peripheral is already - /// disabled will not compile. + /// This method is only available, if `swm::Handle` is in the [`Enabled`] + /// state. Code that attempts to call this method when the peripheral is + /// already disabled will not compile. /// - /// Consumes this instance of `SWM` and returns another instance that has - /// its `State` type parameter set to [`Disabled`]. + /// Consumes this instance of `swm::Handle` and returns another instance + /// that has its `State` type parameter set to [`Disabled`]. /// /// [`Enabled`]: ../init_state/struct.Enabled.html /// [`Disabled`]: ../init_state/struct.Disabled.html diff --git a/src/swm/movable_functions.rs b/src/swm/movable_functions.rs index fc2d22713..f7516355c 100644 --- a/src/swm/movable_functions.rs +++ b/src/swm/movable_functions.rs @@ -39,10 +39,9 @@ macro_rules! movable_functions { $( /// Represents a movable function /// - /// Movable functions can be accessed via the field - /// `movable_functions` of [`swm::Parts`]. + /// Movable functions can be accessed through [`MovableFunctions`]. /// - /// [`swm::Parts`]: struct.Parts.html + /// [`MovableFunctions`]: struct.MovableFunctions.html #[allow(non_camel_case_types)] pub struct $type(()); diff --git a/src/swm/peripheral.rs b/src/swm/peripheral.rs index cad5a8d0d..c866bb14e 100644 --- a/src/swm/peripheral.rs +++ b/src/swm/peripheral.rs @@ -21,6 +21,8 @@ use super::{ /// Please refer to the [module documentation] for more information. /// /// [`swm::Parts`]: struct.Parts.html +/// [`SWM::split`]: #method.split +/// [`SWM::free`]: #method.free /// [`Peripherals`]: ../struct.Peripherals.html /// [module documentation]: index.html pub struct SWM { @@ -41,6 +43,8 @@ impl SWM { /// This is the regular way to access the SWM API. It exists as an explicit /// step, as it's no longer possible to gain access to the raw peripheral /// using [`SWM::free`] after you've called this method. + /// + /// [`SWM::free`]: #method.free pub fn split(self) -> Parts { Parts { handle: Handle::new(self.swm), @@ -68,9 +72,12 @@ impl SWM { /// The main API for the switch matrix (SWM) /// -/// Provides access to all types that make up the SWM API. Please refer to the -/// [module documentation] for more information. +/// Provides access to all types that make up the SWM API. You gain access to +/// this struct by calling [`SWM::split`]. +/// +/// Please refer to the [module documentation] for more information. /// +/// [`SWM::split`]: struct.SWM.html#method.split /// [module documentation]: index.html pub struct Parts { /// Handle to the switch matrix diff --git a/src/swm/state.rs b/src/swm/state.rs index b1ef1edb3..e3ea9f9ae 100644 --- a/src/swm/state.rs +++ b/src/swm/state.rs @@ -5,8 +5,8 @@ use core::marker::PhantomData; /// Implemented by types that indicate the state of SWM functions /// /// This trait is implemented by types that indicate the state of SWM functions. -/// It exists only to document which types those are. The user should not need -/// to implement this trait, nor use it directly. +/// It exists only to document which types those are. Users should not need to +/// implement this trait, nor use it directly. pub trait State { /// Returns an instance of the state /// diff --git a/src/usart.rs b/src/usart.rs index 7f1ea02f5..73accffda 100644 --- a/src/usart.rs +++ b/src/usart.rs @@ -1,7 +1,6 @@ //! API for USART //! -//! The entry point to this API is [`USART`]. Currently, only some limited UART -//! functionality is implemented. +//! The entry point to this API is the [`USART`] struct. //! //! The USART peripheral is described in the user manual, chapter 13. //! @@ -65,6 +64,7 @@ //! //! Please refer to the [examples in the repository] for more example code. //! +//! [`USART`]: struct.USART.html //! [examples in the repository]: https://github.com/lpc-rs/lpc8xx-hal/tree/master/examples mod clock; diff --git a/src/usart/peripheral.rs b/src/usart/peripheral.rs index ab9684055..608494599 100644 --- a/src/usart/peripheral.rs +++ b/src/usart/peripheral.rs @@ -26,15 +26,27 @@ use super::{ /// Controls the USART. Use [`Peripherals`] to gain access to an instance of /// this struct. /// +/// You can either use this struct as-is, if you need to send and receive in the +/// 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. /// /// [`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 pub struct USART { - /// USART Receiver + /// The USART Receiver pub rx: Rx, - /// USART Transmitter + /// The USART Transmitter pub tx: Tx, usart: I, diff --git a/src/usart/rx.rs b/src/usart/rx.rs index 77596ef6b..5b4256660 100644 --- a/src/usart/rx.rs +++ b/src/usart/rx.rs @@ -5,6 +5,10 @@ use crate::{embedded_hal::serial::Read, init_state}; use super::instances::Instance; /// USART receiver +/// +/// This struct implements the [`embedded_hal::serial::Read`] trait. +/// +/// [`embedded_hal::serial::Read`]: https://docs.rs/embedded-hal/0.2.3/embedded_hal/serial/trait.Read.html pub struct Rx { _instance: PhantomData, _state: PhantomData, @@ -100,7 +104,7 @@ pub enum Error { /// Corrupted character received Noise, - /// Character received, while receiver buffer was still in use + /// Character received, while receive buffer was still in use Overrun, /// Parity error detected in received character diff --git a/src/usart/tx.rs b/src/usart/tx.rs index bb0c0b190..14084e68c 100644 --- a/src/usart/tx.rs +++ b/src/usart/tx.rs @@ -11,6 +11,13 @@ use crate::{dma, init_state}; use super::instances::Instance; /// USART transmitter +/// +/// This struct implements the following traits: +/// - [`embedded_hal::serial::Write`] +/// - [`embedded_hal::blocking::serial::Write`] +/// +/// [`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 pub struct Tx { _instance: PhantomData, _state: PhantomData,