Merge pull request 'update docs' (#7) from update-docs into main

Reviewed-on: https://egit.irs.uni-stuttgart.de/rust/va108xx-rs/pulls/7

va108xx-hal/src/gpio/dynpins.rs

@@ -36,8 +36,7 @@
 //! Users may try to convert value-level pins back to their type-level
 //! equivalents. However, this option is fallible, because the compiler cannot
 //! guarantee the pin has the correct ID or is in the correct mode at
-//! compile-time. Use [`TryFrom`](core::convert::TryFrom)/
-//! [`TryInto`](core::convert::TryInto) for this conversion.
+//! compile-time. Use [TryFrom]/[TryInto] for this conversion.
 //!
 //! ```
 //! // Convert to a `DynPin`
@@ -55,7 +54,7 @@
 //! `Error = core::convert::Infallible`, the value-level API can return a real
 //! error. If the [`DynPin`] is not in the correct [`DynPinMode`] for the
 //! operation, the trait functions will return
-//! [`InvalidPinType`](PinError::InvalidPinType).
+//! [InvalidPinTypeError].
 
 use super::{
     pins::{FilterType, InterruptEdge, InterruptLevel, Pin, PinId, PinMode, PinState},

va108xx-hal/src/gpio/pins.rs

@@ -31,20 +31,22 @@
 //!
 //! A `PinId` identifies a pin by it's group (A, B, C or D) and pin number. Each
 //! `PinId` instance is named according to its datasheet identifier, e.g.
-//! [`PA02`].
+//! [PA2].
 //!
 //! A `PinMode` represents the various pin modes. The available `PinMode`
-//! variants are [`Disabled`], [`Input`], [`Interrupt`], [`Output`] and
-//! [`Alternate`], each with its own corresponding configurations.
+//! variants are [`Input`], [`Output`] and [`Alternate`], each with its own
+//! corresponding configurations.
 //!
 //! It is not possible for users to create new instances of a [`Pin`]. Singleton
-//! instances of each pin are made available to users through the [`Pins`]
+//! instances of each pin are made available to users through the PinsX
 //! struct.
 //!
-//! To create the [`Pins`] struct, users must supply the PAC
-//! [`PORT`](crate::pac::PORT) peripheral. The [`Pins`] struct takes
-//! ownership of the [`PORT`] and provides the corresponding pins. Each [`Pin`]
-//! within the [`Pins`] struct can be moved out and used individually.
+//! Example for the pins of PORT A:
+//!
+//! To create the [PinsA] struct, users must supply the PAC
+//! [Port](crate::pac::Porta) peripheral. The [PinsA] struct takes
+//! ownership of the [Porta] and provides the corresponding pins. Each [`Pin`]
+//! within the [PinsA] struct can be moved out and used individually.
 //!
 //!
 //! ```
@@ -67,7 +69,7 @@
 //!
 //! This module implements all of the embedded HAL GPIO traits for each [`Pin`]
 //! in the corresponding [`PinMode`]s, namely: [`InputPin`], [`OutputPin`],
-//! [`ToggleableOutputPin`] and [`StatefulOutputPin`].
+//! and [`StatefulOutputPin`].
 //!
 //! For example, you can control the logic level of an `OutputPin` like so
 //!
@@ -80,21 +82,6 @@
 //! let mut pins = Pins::new(peripherals.PORT);
 //! pins.pa27.set_high();
 //! ```
-//!
-//! # Type-level features
-//!
-//! This module also provides additional, type-level tools to work with GPIO
-//! pins.
-//!
-//! The [`OptionalPinId`] and [`OptionalPin`] traits use the [`OptionalKind`]
-//! pattern to act as type-level versions of [`Option`] for `PinId` and `Pin`
-//! respectively. And the [`AnyPin`] trait defines an [`AnyKind`] type class
-//! for all `Pin` types.
-//!
-//! [type classes]: crate::typelevel#type-classes
-//! [type-level enum]: crate::typelevel#type-level-enum
-//! [`OptionalKind`]: crate::typelevel#optionalkind-trait-pattern
-//! [`AnyKind`]: crate::typelevel#anykind-trait-pattern
 use super::dynpins::{DynAlternate, DynGroup, DynInput, DynOutput, DynPinId, DynPinMode};
 use super::reg::RegisterInterface;
 use crate::{
@@ -137,9 +124,9 @@ pub enum PinState {
 
 /// Type-level enum for input configurations
 ///
-/// The valid options are [`Floating`], [`PullDown`] and [`PullUp`].
+/// The valid options are [Floating], [PullDown] and [PullUp].
 pub trait InputConfig: Sealed {
-    /// Corresponding [`DynInput`](super::DynInput)
+    /// Corresponding [DynInput]
     const DYN: DynInput;
 }
 
@@ -297,9 +284,9 @@ pub type Reset = InputFloating;
 
 /// Type-level enum representing pin modes
 ///
-/// The valid options are [`Input`], [`Output`] and [`Alternate`].
+/// The valid options are [Input], [Output] and [Alternate].
 pub trait PinMode: Sealed {
-    /// Corresponding [`DynPinMode`](super::DynPinMode)
+    /// Corresponding [DynPinMode]
     const DYN: DynPinMode;
 }
 
@@ -319,7 +306,7 @@ impl<C: AlternateConfig> PinMode for Alternate<C> {
 
 /// Type-level enum for pin IDs
 pub trait PinId: Sealed {
-    /// Corresponding [`DynPinId`](super::DynPinId)
+    /// Corresponding [DynPinId]
     const DYN: DynPinId;
 }
 
@@ -344,20 +331,20 @@ macro_rules! pin_id {
 //  Pin
 //==================================================================================================
 
-/// A type-level GPIO pin, parameterized by [`PinId`] and [`PinMode`] types
+/// A type-level GPIO pin, parameterized by [PinId] and [PinMode] types
 
 pub struct Pin<I: PinId, M: PinMode> {
     pub(in crate::gpio) regs: Registers<I>,
     mode: PhantomData<M>,
 }
 
 impl<I: PinId, M: PinMode> Pin<I, M> {
-    /// Create a new [`Pin`]
+    /// Create a new [Pin]
     ///
     /// # Safety
     ///
-    /// Each [`Pin`] must be a singleton. For a given [`PinId`], there must be
-    /// at most one corresponding [`Pin`] in existence at any given time.
+    /// Each [Pin] must be a singleton. For a given [PinId], there must be
+    /// at most one corresponding [Pin] in existence at any given time.
     /// Violating this requirement is `unsafe`.
     #[inline]
     pub(crate) unsafe fn new() -> Pin<I, M> {

va108xx-hal/src/sysconfig.rs

@@ -1,18 +1,19 @@
 use crate::{pac, PeripheralSelect};
 
 #[derive(PartialEq, Eq, Debug)]
-pub struct InvalidounterResetVal(pub(crate) ());
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub struct InvalidCounterResetVal(pub(crate) ());
 
 /// Enable scrubbing for the ROM
 ///
-/// Returns [`UtilityError::InvalidCounterResetVal`] if the scrub rate is 0
+/// Returns [InvalidCounterResetVal] if the scrub rate is 0
 /// (equivalent to disabling) or larger than 24 bits
 pub fn enable_rom_scrubbing(
     syscfg: &mut pac::Sysconfig,
     scrub_rate: u32,
-) -> Result<(), InvalidounterResetVal> {
+) -> Result<(), InvalidCounterResetVal> {
     if scrub_rate == 0 || scrub_rate > u32::pow(2, 24) {
-        return Err(InvalidounterResetVal(()));
+        return Err(InvalidCounterResetVal(()));
     }
     syscfg.rom_scrub().write(|w| unsafe { w.bits(scrub_rate) });
     Ok(())
@@ -24,14 +25,14 @@ pub fn disable_rom_scrubbing(syscfg: &mut pac::Sysconfig) {
 
 /// Enable scrubbing for the RAM
 ///
-/// Returns [`UtilityError::InvalidCounterResetVal`] if the scrub rate is 0
+/// Returns [InvalidCounterResetVal] if the scrub rate is 0
 /// (equivalent to disabling) or larger than 24 bits
 pub fn enable_ram_scrubbing(
     syscfg: &mut pac::Sysconfig,
     scrub_rate: u32,
-) -> Result<(), InvalidounterResetVal> {
+) -> Result<(), InvalidCounterResetVal> {
     if scrub_rate == 0 || scrub_rate > u32::pow(2, 24) {
-        return Err(InvalidounterResetVal(()));
+        return Err(InvalidCounterResetVal(()));
     }
     syscfg.ram_scrub().write(|w| unsafe { w.bits(scrub_rate) });
     Ok(())