Merge pull request #170 from Sh3Rm4n/doc-n-msvr

Sh3Rm4n · web-flow · commit 969d63479b84 · 2020-12-03T14:22:17.000+01:00
Improve documentation and set MSRV
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -49,6 +49,25 @@ jobs:
           command: check
           args: --features=${{ matrix.mcu }},${{ matrix.features }} --lib --examples
 
+  # This is our MSRV. However this is only for documentation
+  # purposes and should be increased if newer features are used.
+  # This should not stop anyone from bumping the MSRV.
+  check-msrv:
+    name: Check MSRV
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: 1.48.0
+          target: thumbv7em-none-eabihf
+          override: true
+          profile: minimal
+      - uses: actions-rs/cargo@v1
+        with:
+          command: check
+          args: --features=stm32f303xc,stm32-usbd,rt,can --lib --examples
+
   clippy:
     name: Clippy
     runs-on: ubuntu-latest
@@ -65,7 +84,7 @@ jobs:
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           args: >
-            --features=stm32f303xc,rt,stm32-usbd --lib --examples
+            --features=stm32f303xc,rt,stm32-usbd,can --lib --examples
             -- -D warnings
 
   rustfmt:
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -31,7 +31,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Fixed
 
-- Fixed [#151][] not being able to generate 72 MHz HCLK for stm32f303xc devices 
+- Fixed [#151][] not being able to generate 72 MHz HCLK for stm32f303xc devices
   ([#152](https://github.com/stm32-rs/stm32f3xx-hal/pull/152))
 
 [#151]: https://github.com/stm32-rs/stm32f3xx-hal/issues/151
@@ -42,6 +42,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   `stm32f378` targets. ([#99](https://github.com/stm32-rs/stm32f3xx-hal/pull/99))
 - Removed SPI1 support for `stm32f302x6` and `stm32f302x8` sub-targets
   and `stm32f318` target. ([#99](https://github.com/stm32-rs/stm32f3xx-hal/pull/99))
+- This release requires 1.48, as intra-doc-links are now used internally.
+  Until now, no MSRV was tracked. This has changed now. This however does
+  not mean, that we guarantee any MSRV policy. It is rather for documentation
+  purposes and if a new useful feature arises, we will increase the MSRV.
+  ([#170](https://github.com/stm32-rs/stm32f3xx-hal/pull/170))
 
 ## [v0.5.0] - 2020-07-21
 
diff --git a/Cargo.toml b/Cargo.toml
@@ -19,7 +19,7 @@ exclude = [
 ]
 
 [package.metadata.docs.rs]
-features = ["stm32f303xc", "rt", "stm32-usbd"]
+features = ["stm32f303xc", "rt", "stm32-usbd", "can"]
 targets = ["thumbv7em-none-eabihf"]
 
 [dependencies]
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# stm32f3xx-hal
+# `stm32f3xx-hal`
 
 [![Build Status](https://github.com/stm32-rs/stm32f3xx-hal/workflows/CI/badge.svg)](https://github.com/stm32-rs/stm32f3xx-hal/actions)
 [![Crate](https://img.shields.io/crates/v/stm32f3xx-hal.svg)](https://crates.io/crates/stm32f3xx-hal)
@@ -38,6 +38,8 @@ Almost all of the implementation was shamelessly adapted from the
 [`stm32f30x-hal`]: https://github.com/japaric/stm32f30x-hal
 [`embedded-hal`]: https://github.com/japaric/embedded-hal
 
+## [Changelog](CHANGELOG.md)
+
 ## Selecting the right chip
 
 This crate requires you to specify your target chip as a feature.
diff --git a/examples/can.rs b/examples/can.rs
@@ -81,7 +81,7 @@ fn main() -> ! {
             }
 
             let data: [u8; 1] = [counter];
-            let frame = CanFrame::data_frame(CanId::BaseId(ID.into()), &data);
+            let frame = CanFrame::data_frame(CanId::BaseId(ID), &data);
 
             block!(can_tx.transmit(&frame)).expect("Cannot send CAN frame");
         }
diff --git a/src/can.rs b/src/can.rs
@@ -1,4 +1,11 @@
 //! Controller Area Network
+//!
+//! CAN is currently not enabled by default, and
+//! can be enabled by the `can` feature.
+//!
+//! It is a implementation of the [`embedded_hal_can`][can] traits.
+//!
+//! [can]: embedded_hal_can
 pub use embedded_hal_can::{self, Filter, Frame, Id, Receiver, Transmitter};
 
 use crate::gpio::gpioa;
@@ -10,10 +17,11 @@ use nb::{self, Error};
 
 use core::sync::atomic::{AtomicU8, Ordering};
 
-const EXID_MASK: u32 = 0b11111_11111100_00000000_00000000;
+const EXID_MASK: u32 = 0b1_1111_1111_1100_0000_0000_0000_0000;
 const MAX_EXTENDED_ID: u32 = 0x1FFF_FFFF;
 
-/// A CAN identifier, which can be either 11 or 27 (extended) bits. u16 and u32 respectively are used here despite the fact that the upper bits are unused.
+/// A CAN identifier, which can be either 11 or 27 (extended) bits.
+/// u16 and u32 respectively are used here despite the fact that the upper bits are unused.
 #[derive(Debug, Copy, Clone, Eq, PartialEq)]
 pub enum CanId {
     BaseId(u16),
@@ -22,14 +30,16 @@ pub enum CanId {
 
 /// A CAN frame consisting of a destination ID and up to 8 bytes of data.
 ///
-/// Currently, we always allocate a fixed size array for each frame regardless of actual size, but this could be improved in the future using const-generics.
+/// Currently, we always allocate a fixed size array for each frame regardless
+/// of actual size, but this could be improved in the future using const-generics.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct CanFrame {
     pub id: CanId,
     pub data: Vec<u8, U8>,
 }
 
-/// Represents the operating mode of a CAN filter, which can either contain a list of identifiers, or a mask to match on.
+/// Represents the operating mode of a CAN filter, which can either contain a
+/// list of identifiers, or a mask to match on.
 pub enum FilterMode {
     Mask,
     List,
@@ -58,7 +68,8 @@ pub struct Can {
     _tx: gpioa::PA12<AF9>,
 }
 
-/// A CAN FIFO which is used to receive and buffer messages from the CAN network that match on of the assigned filters.
+/// A CAN FIFO which is used to receive and buffer messages from the CAN
+/// network that match on of the assigned filters.
 pub struct CanFifo {
     idx: usize,
 }
@@ -140,9 +151,12 @@ impl embedded_hal_can::Filter for CanFilter {
         CanFilter::new(CanFilterData::AcceptAll)
     }
 
-    // TODO: Constructing filters like this is fairly limiting because ideally we would have the full "filter state" available, so for non-extended filters this could be 2 masks and filters or 4 ids for id lists
+    // TODO: Constructing filters like this is fairly limiting because ideally
+    // we would have the full "filter state" available, so for non-extended
+    // filters this could be 2 masks and filters or 4 ids for id lists
 
-    /// Constuct a mask filter. This method accepts two parameters, the mask which designates which bits are actually matched againts and the filter, with the actual bits to match.
+    /// Constuct a mask filter. This method accepts two parameters, the mask which designates which
+    /// bits are actually matched againts and the filter, with the actual bits to match.
     fn from_mask(mask: u32, filter: u32) -> Self {
         assert!(
             mask < MAX_EXTENDED_ID,
@@ -159,7 +173,8 @@ impl embedded_hal_can::Filter for CanFilter {
 }
 
 impl CanFilter {
-    /// Create a new filter with no assigned index. To actually active the filter call `Receiver::set_filter`, which will assign an index.
+    /// Create a new filter with no assigned index. To actually active the filter call
+    /// [`Receiver::set_filter`], which will assign an index.
     pub fn new(data: CanFilterData) -> CanFilter {
         CanFilter { data, index: None }
     }
@@ -179,7 +194,8 @@ impl CanFilterData {
             CanFilterData::AcceptAll => 0,
             CanFilterData::ExtendedMaskFilter(filter, _) => filter << 3,
             CanFilterData::MaskFilter(filter, mask) => {
-                let shifted_filter = ((*filter as u32) << 5) & (u16::max_value() as u32); // Only use lower 16 bits
+                // Only use lower 16 bits
+                let shifted_filter = ((*filter as u32) << 5) & (u16::max_value() as u32);
                 let shifted_mask = ((*mask as u32) << 5) << 16;
 
                 shifted_filter | shifted_mask
@@ -195,8 +211,10 @@ impl CanFilterData {
         match self {
             CanFilterData::AcceptAll => Some(0),
             CanFilterData::ExtendedMaskFilter(_, mask) => Some(mask << 3),
-            CanFilterData::MaskFilter(_, _mask) => None, // TODO: We should be able to fill this register with a second filter/mask pair
-            CanFilterData::IdFilter(_id) => None, // TODO: This sucks, we need more info here to figure out the correct value of fr2
+            // TODO: We should be able to fill this register with a second filter/mask pair
+            CanFilterData::MaskFilter(_, _mask) => None,
+            // TODO: This sucks, we need more info here to figure out the correct value of fr2
+            CanFilterData::IdFilter(_id) => None,
         }
     }
 }
@@ -284,7 +302,7 @@ impl Can {
             _tx: self._tx,
         };
 
-        return (transmitter, fifo0, fifo1);
+        (transmitter, fifo0, fifo1)
     }
 
     pub fn free(self) -> (stm32::CAN, gpioa::PA11<AF9>, gpioa::PA12<AF9>) {
@@ -335,7 +353,7 @@ impl embedded_hal_can::Transmitter for CanTransmitter {
                 }),
             }
 
-            if let Some(_) = frame.data() {
+            if frame.data().is_some() {
                 for j in 0..frame.data.len() {
                     let val = &frame.data[j];
 
diff --git a/src/gpio.rs b/src/gpio.rs
@@ -1,7 +1,7 @@
 //! General Purpose Input / Output
 //!
 //! To use the GPIO pins, you first need to configure the GPIO bank (GPIOA, GPIOB, ...) that you
-//! are interested in. This is done using the [GpioExt::split](trait.GpioExt.html#tymethod.split) function.
+//! are interested in. This is done using the [`GpioExt::split`] function.
 //!
 //! ```
 //! let dp = pac::Peripherals::take().unwrap();
@@ -10,10 +10,10 @@
 //! let mut gpioa = dp.GPIOA.split(&mut rcc.ahb);
 //! ```
 //!
-//! The resulting [Parts](gpioa/struct.Parts.html) struct contains one field for each
+//! The resulting [Parts](gpioa::Parts) struct contains one field for each
 //! pin, as well as some shared registers.
 //!
-//! To use a pin, first use the relevant `into_...` method of the [pin](gpioa/struct.PA0.html).
+//! To use a pin, first use the relevant `into_...` method of the [pin](gpioa::PA0).
 //!
 //! ```rust
 //! let pa0 = gpioa.pa0.into_push_pull_output(&mut gpioa.moder, &mut gpioa.otyper);
@@ -24,8 +24,8 @@
 //!
 //! For a complete example, see [examples/toggle.rs]
 //!
-//! [InputPin]: ../prelude/trait._embedded_hal_digital_InputPin.html
-//! [OutputPin]: ../prelude/trait._embedded_hal_digital_OutputPin.html
+//! [InputPin]: embedded_hal::digital::v2::InputPin
+//! [OutputPin]: embedded_hal::digital::v2::OutputPin
 //! [examples/toggle.rs]: https://github.com/stm32-rs/stm32f3xx-hal/blob/v0.4.3/examples/toggle.rs
 
 use core::convert::Infallible;
@@ -43,7 +43,7 @@ use crate::rcc::AHB;
 
 /// Extension trait to split a GPIO peripheral in independent pins and registers
 pub trait GpioExt {
-    /// The to split the GPIO into
+    /// The Parts to split the GPIO peripheral into
     type Parts;
 
     /// Splits the GPIO block into independent pins and registers
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,4 +1,13 @@
 /*!
+ # stm32f3xx-hal
+
+ `stm32f3xx-hal` contains a multi device hardware abstraction on top of the
+ peripheral access API for the STMicro [STM32F3][stm] series microcontrollers. The
+ selection of the MCU is done by [feature][f] gates
+
+ [f]: #selecting-the-right-chip
+ [stm]: https://www.st.com/en/microcontrollers-microprocessors/stm32f3-series.html
+
  # Selecting the right chip
 
    This crate requires you to specify your target chip as a feature.
@@ -87,25 +96,32 @@ pub use nb;
 pub use nb::block;
 
 #[cfg(any(feature = "stm32f301", feature = "stm32f318"))]
+/// Peripheral access
 pub use stm32f3::stm32f301 as pac;
 
 #[cfg(feature = "stm32f302")]
+/// Peripheral access
 pub use stm32f3::stm32f302 as pac;
 
 #[cfg(feature = "stm32f303")]
+/// Peripheral access
 pub use stm32f3::stm32f303 as pac;
 
 #[cfg(any(feature = "stm32f373", feature = "stm32f378"))]
+/// Peripheral access
 pub use stm32f3::stm32f373 as pac;
 
 #[cfg(feature = "stm32f334")]
+/// Peripheral access
 pub use stm32f3::stm32f3x4 as pac;
 
 #[cfg(any(feature = "stm32f328", feature = "stm32f358", feature = "stm32f398"))]
+/// Peripheral access
 pub use stm32f3::stm32f3x8 as pac;
 
 #[cfg(feature = "device-selected")]
 #[deprecated(since = "0.5.0", note = "please use `pac` instead")]
+/// Peripheral access
 pub use crate::pac as stm32;
 
 // Enable use of interrupt macro
diff --git a/src/rcc.rs b/src/rcc.rs
diff --git a/src/rtc.rs b/src/rtc.rs

Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,7 @@ exclude = [`
`19`	`19`	`]`
`20`	`20`
`21`	`21`	`[package.metadata.docs.rs]`
`22`		`-features = ["stm32f303xc", "rt", "stm32-usbd"]`
	`22`	`+features = ["stm32f303xc", "rt", "stm32-usbd", "can"]`
`23`	`23`	`targets = ["thumbv7em-none-eabihf"]`
`24`	`24`
`25`	`25`	`[dependencies]`
Original file line number	Diff line number	Diff line change
`@@ -81,7 +81,7 @@ fn main() -> ! {`
`81`	`81`	`}`
`82`	`82`
`83`	`83`	`let data: [u8; 1] = [counter];`
`84`		`- let frame = CanFrame::data_frame(CanId::BaseId(ID.into()), &data);`
	`84`	`+ let frame = CanFrame::data_frame(CanId::BaseId(ID), &data);`
`85`	`85`
`86`	`86`	`block!(can_tx.transmit(&frame)).expect("Cannot send CAN frame");`
`87`	`87`	`}`