Improve documentation for BitrateBuilder (#102)

* add example

* add to docs

* add missing trait

Author: pd0wm

.github/workflows/linux-windows.yml

@@ -19,3 +19,5 @@ jobs:
           sudo apt-get -y install clang gcc-mingw-w64-x86-64 libclang-dev
       - name: Build
         run: cargo build --verbose --target=x86_64-pc-windows-gnu --features=all
+      - name: Build Examples
+        run: cargo build --verbose --target=x86_64-pc-windows-gnu --features=all --examples

.github/workflows/linux.yml

@@ -19,5 +19,7 @@ jobs:
           scripts/set_up_vcan.sh
       - name: Build
         run: cargo build --verbose --features=serde
+      - name: Build Examples
+        run: cargo build --verbose --features=serde --examples
       - name: Run tests
         run: cargo test --features=test-vcan,serde --verbose

.github/workflows/macos.yml

@@ -13,5 +13,7 @@ jobs:
       - uses: actions/checkout@v3
       - name: Build
         run: cargo build --verbose --features=serde
+      - name: Build Examples
+        run: cargo build --verbose --features=serde --examples
       - name: Run tests
         run: cargo test --features=serde --verbose

.github/workflows/windows.yml

@@ -13,5 +13,7 @@ jobs:
       - uses: actions/checkout@v3
       - name: Build
         run: cargo build --verbose --features=all
+      - name: Build Examples
+        run: cargo build --verbose --features=all --examples
       - name: Run tests
         run: cargo test --features=all --verbose

examples/configure_bitrate.rs

@@ -0,0 +1,36 @@
+#[cfg(all(target_os = "windows", feature = "vector-xl"))]
+pub async fn run() -> automotive::Result<()> {
+    use automotive::can::bitrate::BitrateBuilder;
+    use automotive::vector::VectorCan;
+    use automotive::StreamExt;
+
+    tracing_subscriber::fmt::init();
+
+    let bitrate_cfg = BitrateBuilder::new::<VectorCan>()
+        .bitrate(500_000)
+        .sample_point(0.8)
+        .data_bitrate(2_000_000)
+        .data_sample_point(0.8)
+        .build()
+        .unwrap();
+
+    let adapter = VectorCan::new_async(0, &Some(bitrate_cfg.into()))?;
+    let mut stream = adapter.recv();
+
+    while let Some(frame) = stream.next().await {
+        println!("{:?}", frame);
+    }
+
+    Ok(())
+}
+
+#[cfg(all(target_os = "windows", feature = "vector-xl"))]
+#[tokio::main]
+async fn main() -> automotive::Result<()> {
+    run().await
+}
+
+#[cfg(not(all(target_os = "windows", feature = "vector-xl")))]
+fn main() {
+    eprintln!("This example requires Windows and the `vector-xl` feature.");
+}

src/can/bitrate.rs

@@ -15,6 +15,56 @@
 //! The resulting [`BitrateConfig`] contains:
 //! - nominal/arbitration phase settings as one [`AdapterBitTiming`]
 //! - optional CAN-FD data phase settings as one [`AdapterBitTiming`]
+//!
+//! ## Example
+//!
+//! Build a 500 kbit/s nominal bitrate configuration using the timing constants
+//! exposed by an adapter type:
+//!
+//! ```rust
+//! use automotive::can::bitrate::{AdapterTimingConst, BitTimingConst, BitrateBuilder};
+//! use automotive::can::{CanAdapter, Frame};
+//! use std::collections::VecDeque;
+//!
+//! # const TIMING: AdapterTimingConst = AdapterTimingConst {
+//! #     nominal: BitTimingConst {
+//! #         clock_hz: 80_000_000,
+//! #         tseg1_min: 1,
+//! #         tseg1_max: 16,
+//! #         tseg2_min: 1,
+//! #         tseg2_max: 8,
+//! #         sjw_max: 4,
+//! #         brp_min: 1,
+//! #         brp_max: 1024,
+//! #         brp_inc: 1,
+//! #     },
+//! #     data: None,
+//! # };
+//! # struct DummyAdapter;
+//! # impl CanAdapter for DummyAdapter {
+//! #     fn send(&mut self, _frames: &mut VecDeque<Frame>) -> automotive::Result<()> {
+//! #         unreachable!()
+//! #     }
+//! #
+//! #     fn recv(&mut self) -> automotive::Result<Vec<Frame>> {
+//! #         unreachable!()
+//! #     }
+//! #
+//! #     fn timing_const() -> AdapterTimingConst
+//! #     where
+//! #         Self: Sized,
+//! #     {
+//! #         TIMING
+//! #     }
+//! # }
+//! let bitrate_cfg = BitrateBuilder::new::<DummyAdapter>()
+//!     .bitrate(500_000)
+//!     .sample_point(0.8)
+//!     .build()?;
+//!
+//! assert_eq!(bitrate_cfg.nominal.bitrate, 500_000);
+//! # Ok::<(), automotive::can::bitrate::BitrateError>(())
+//! ```
 
 use thiserror::Error;