Fix documentation lints (#152)

* Fix documentation lints

* Use nightly to test documentation

---------

Co-authored-by: James Munns <[email protected]>

ci.sh

@@ -7,6 +7,18 @@ has_target() {
 ensure_target() {
   has_target "$1" || rustup target add "$1"
 }
+
+ensure_target thumbv7em-none-eabi
+
+has_toolchain() {
+  rustup toolchain list | grep -q "$1"
+}
+ensure_toolchain() {
+  has_toolchain "$1" || rustup toolchain install "$1"
+}
+
+ensure_toolchain nightly-x86_64-unknown-linux-gnu
+
 cargo_check() {
   cargo check "$@"
   cargo clippy "$@" -- --deny=warnings
@@ -18,14 +30,12 @@ cargo_test() {
 
 cargo_test --features=alloc,experimental-derive,use-std,use-crc
 
-ensure_target thumbv7em-none-eabi
 cargo_check --target=thumbv7em-none-eabi --no-default-features
 cargo_check --target=thumbv7em-none-eabi --features=alloc,experimental-derive
 
 cargo fmt -- --check
 
-# TODO: Uncomment once documentation lints are fixed.
-# env RUSTDOCFLAGS='--cfg=docsrs --deny=warnings' cargo doc --no-deps
+env RUSTDOCFLAGS='--cfg=docsrs --deny=warnings' cargo +nightly doc --no-deps --all-features
 
 cd postcard-derive
 

src/eio.rs

@@ -1,7 +1,9 @@
-#[cfg(all(feature = "embedded-io-04", feature = "embedded-io-06"))]
+// We disable all embedded-io versions but the most recent in docs.rs, because we use
+// --all-features which doesn't work with non-additive features.
+#[cfg(all(feature = "embedded-io-04", feature = "embedded-io-06", not(docsrs)))]
 compile_error!("Only one version of `embedded-io` must be enabled through features");
 
-#[cfg(feature = "embedded-io-04")]
+#[cfg(all(feature = "embedded-io-04", not(docsrs)))]
 mod version_impl {
     pub use embedded_io_04 as embedded_io;
     pub use embedded_io_04::blocking::{Read, Write};

src/ser/flavors.rs

@@ -212,7 +212,7 @@ impl<'a> IndexMut<usize> for Slice<'a> {
     }
 }
 
-/// Wrapper over a [std::iter::Extend<u8>] that implements the flavor trait
+/// Wrapper over a [`std::iter::Extend<u8>`] that implements the flavor trait
 pub struct ExtendFlavor<T> {
     iter: T,
 }
@@ -221,7 +221,7 @@ impl<T> ExtendFlavor<T>
 where
     T: core::iter::Extend<u8>,
 {
-    /// Create a new [Self] flavor from a given [std::iter::Extend<u8>]
+    /// Create a new [Self] flavor from a given [`std::iter::Extend<u8>`]
     pub fn new(iter: T) -> Self {
         Self { iter }
     }