Improve documentation

Make sure the docs.rs documentation shows the features required for the
various backend. Also fix some doc lint issue due to better
autoresolving in rustdoc

.github/workflows/ci.yml

@@ -14,6 +14,7 @@ jobs:
       - uses: actions/checkout@v3
       - uses: dtolnay/rust-toolchain@1.81
       - run: cargo test --all-targets --all-features
+      - run: cargo test --docs --all-features
 
   fmt:
     name: cargo fmt
@@ -33,7 +34,7 @@ jobs:
       - uses: dtolnay/rust-toolchain@1.81
         with:
             components: clippy
-      - run: cargo clippy --all-targets -- -D warnings
+      - run: cargo clippy --all-targets --all-features -- -D warnings
 
   allgreen:
     if: always()

rockusb/Cargo.toml

@@ -38,6 +38,10 @@ futures = { version = "0.3.31", features = ["compat", "io-compat"]}
 tokio-util = { version = "0.7.12", features = ["compat"] }
 async-compression = { version = "0.4.5", features = ["gzip", "futures-io"] }
 
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
+
 [[example]]
 name="rockusb"
 required-features = ["libusb"]

rockusb/README.md

@@ -2,15 +2,29 @@
 
 Rockchip bootroms and early loaders implement an USB protocol to help loader
 early firmware, flashing persistant storage etc. This crate contains a sans-io
-implementation of that protocol as well as an optional (enabled by default)
-implementation of IO using libusb
+implementation of that protocol as well as an optional implementations of IO
+using libusb or nusb.
 
+Printing chip info using libusb backend:
 ```rust,no_run
-fn main() -> anyhow::Result<()> {
-    let devices = rockusb::libusb::Devices::new()?;
-    let mut transport = devices.iter().next()
-    	.ok_or_else(|| anyhow::anyhow!("No Device found"))??;
-    println!("Chip Info: {:0x?}", transport.chip_info()?);
-    Ok(())
-}
+# fn main() -> anyhow::Result<()> {
+let devices = rockusb::libusb::Devices::new()?;
+let mut transport = devices.iter().next()
+    .ok_or_else(|| anyhow::anyhow!("No Device found"))??;
+println!("Chip Info: {:0x?}", transport.chip_info()?);
+Ok(())
+# }
+```
+
+Printing chip info using nusb backend:
+```rust,no_run
+# #[tokio::main]
+# async fn main() -> anyhow::Result<()> {
+let mut devices = rockusb::nusb::devices()?;
+let info = devices.next()
+    .ok_or_else(|| anyhow::anyhow!("No Device found"))?;
+let mut transport = rockusb::nusb::Transport::from_usb_device_info(info)?;
+println!("Chip Info: {:0x?}", transport.chip_info().await?);
+Ok(())
+# }
 ```

rockusb/src/lib.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 #![doc = include_str!("../README.md")]
 
 /// libusb transport implementation
@@ -6,7 +7,7 @@ pub mod libusb;
 /// nusb transport implementation
 #[cfg(feature = "nusb")]
 pub mod nusb;
-/// sans-io protocol implementationsss
+/// sans-io protocol implementations
 ///
 /// This module contains all protocol logic; Each operation implements the [operation::OperationSteps]
 /// trait which gives a transport a series of [operation::UsbStep] to execute to complete an

rockusb/src/libusb.rs

@@ -148,14 +148,14 @@ impl Transport {
         })
     }
 
-    /// Create an IO object which implements [Read](std::io::Read), [Write](std::io::Write) and
-    /// [Seek](std::io::Seek)
+    /// Create an IO object which implements [Read], [Write] and
+    /// [Seek]
     pub fn io(&mut self) -> Result<TransportIO<&mut Self>> {
         TransportIO::new(self)
     }
 
-    /// Convert into an IO object which implements [Read](std::io::Read), [Write](std::io::Write) and
-    /// [Seek](std::io::Seek)
+    /// Convert into an IO object which implements [Read], [Write] and
+    /// [Seek]
     pub fn into_io(self) -> Result<TransportIO<Self>> {
         TransportIO::new(self)
     }
@@ -230,17 +230,17 @@ impl Transport {
 
     /// read from the flash
     ///
-    /// start_sector with [SECTOR_SIZE](crate::protocol::SECTOR_SIZE) sectors. the data to be read
-    /// must be a multiple of [SECTOR_SIZE](crate::protocol::SECTOR_SIZE) bytes
+    /// start_sector with [SECTOR_SIZE] sectors. the data to be read
+    /// must be a multiple of [SECTOR_SIZE] bytes
     pub fn read_lba(&mut self, start_sector: u32, read: &mut [u8]) -> Result<u32> {
         self.handle_operation(crate::operation::read_lba(start_sector, read))
             .map(|t| t.into())
     }
 
     /// Create operation to read an lba from the flash
     ///
-    /// start_sector based on [SECTOR_SIZE](crate::protocol::SECTOR_SIZE) sectors. the data to be
-    /// written must be a multiple of [SECTOR_SIZE](crate::protocol::SECTOR_SIZE) bytes
+    /// start_sector based on [SECTOR_SIZE] sectors. the data to be
+    /// written must be a multiple of [SECTOR_SIZE] bytes
     pub fn write_lba(&mut self, start_sector: u32, write: &[u8]) -> Result<u32> {
         self.handle_operation(crate::operation::write_lba(start_sector, write))
             .map(|t| t.into())
@@ -258,8 +258,7 @@ impl Transport {
     }
 }
 
-/// IO object which implements [Read](std::io::Read), [Write](std::io::Write) and
-/// [Seek](std::io::Seek)
+/// IO object which implements [Read], [Write] and [Seek]
 pub struct TransportIO<T> {
     transport: T,
     size: u64,

rockusb/src/nusb.rs

@@ -95,8 +95,8 @@ impl Transport {
         })
     }
 
-    /// Convert into an IO object which implements [AsyncRead](futures::io::AsyncRead),
-    /// [AsyncWrite](futures::io::AsyncWrite) and [AsyncSeek](futures::io::AsyncSeek)
+    /// Convert into an IO object which implements [AsyncRead],
+    /// [AsyncWrite] and [AsyncSeek]
     pub async fn into_io(self) -> Result<TransportIO> {
         TransportIO::new(self).await
     }
@@ -178,8 +178,8 @@ impl Transport {
 
     /// read from the flash
     ///
-    /// start_sector with [SECTOR_SIZE](crate::protocol::SECTOR_SIZE) sectors. the data to be read
-    /// must be a multiple of [SECTOR_SIZE](crate::protocol::SECTOR_SIZE) bytes
+    /// start_sector with [SECTOR_SIZE] sectors. the data to be read
+    /// must be a multiple of [SECTOR_SIZE] bytes
     pub async fn read_lba(&mut self, start_sector: u32, read: &mut [u8]) -> Result<u32> {
         self.handle_operation(crate::operation::read_lba(start_sector, read))
             .await
@@ -188,8 +188,8 @@ impl Transport {
 
     /// Create operation to read an lba from the flash
     ///
-    /// start_sector based on [SECTOR_SIZE](crate::protocol::SECTOR_SIZE) sectors. the data to be
-    /// written must be a multiple of [SECTOR_SIZE](crate::protocol::SECTOR_SIZE) bytes
+    /// start_sector based on [SECTOR_SIZE] sectors. the data to be
+    /// written must be a multiple of [SECTOR_SIZE] bytes
     pub async fn write_lba(&mut self, start_sector: u32, write: &[u8]) -> Result<u32> {
         self.handle_operation(crate::operation::write_lba(start_sector, write))
             .await
@@ -228,8 +228,7 @@ struct TransportIOInner {
     state: BufferState,
 }
 
-/// IO object which implements [AsyncRead](futures::io::AsyncRead),
-/// [AsyncWrite](futures::io::AsyncWrite) and [AsyncSeek](futures::io::AsyncSeek)
+/// IO object which implements [AsyncRead], [AsyncWrite] and [AsyncSeek]
 pub struct TransportIO {
     // io execution state
     io_state: IoState,