Merge pull request #53 from phip1611/restructure

Improve documentation examples and streamline architecture support

Author: phip1611

.github/workflows/rust.yml

@@ -92,10 +92,15 @@ jobs:
       - run: rustup component add miri
       - run: cargo miri test --tests
 
+  # Style + documentation checks
   style_checks:
-    runs-on: ubuntu-latest
+    runs-on: "${{ matrix.runs-on }}"
     strategy:
       matrix:
+        runs-on:
+          - macos-latest # aarch64
+          - ubuntu-latest # x86_64
+          - windows-latest # x86_64
         rust:
           - stable
     steps:
@@ -113,3 +118,7 @@ jobs:
         run: cargo clippy --all-targets
       - name: Rustdoc
         run: cargo doc --no-deps --document-private-items
+      - name: Rustdoc (doc_cfg + nightly)
+        env:
+          RUSTDOCFLAGS: --cfg docsrs
+        run: cargo +nightly doc --no-deps --document-private-items

Cargo.toml

@@ -31,3 +31,7 @@ assert2 = { version = "0.4.0", default-features = false, features = [] }
 [features]
 default = []
 embedded-io = ["dep:embedded-io"]
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

README.md

@@ -46,10 +46,24 @@ layer.
 
 # Overview
 
-Use `Uart16550Tty` for a quick start. For more fine-grained low-level
-control, please have a look at `Uart16550` instead.
+Use `Uart16550Tty` for a quick start to write to a terminal via your serial
+connection. For more fine-grained low-level control, please have a look at
+`Uart16550` instead.
 
-# Example (Minimalistic)
+# Example (Minimal - x86 Port IO)
+
+```rust
+use uart_16550::{Config, Uart16550Tty};
+use core::fmt::Write;
+
+fn main() {
+  // SAFETY: The port is valid and we have exclusive access.
+  let mut uart = unsafe { Uart16550Tty::new_port(0x3f8, Config::default()).expect("should initialize device") };
+  uart.write_str("hello world\nhow's it going?");
+}
+```
+
+# Example (Minimal - MMIO)
 
 ```rust
 use uart_16550::{Config, Uart16550Tty};
@@ -58,7 +72,6 @@ use core::fmt::Write;
 fn main() {
   // SAFETY: The address is valid and we have exclusive access.
   let mut uart = unsafe { Uart16550Tty::new_mmio(0x1000 as *mut _, 4, Config::default()).expect("should initialize device") };
-  //                                    ^ or `new_port(0x3f8, Config::default())`
   uart.write_str("hello world\nhow's it going?");
 }
 ```
@@ -74,6 +87,7 @@ fn main() {
   //                                 ^ or `new_port(0x3f8)`
   uart.init(Config::default()).expect("should init device successfully");
   uart.test_loopback().expect("should have working loopback mode");
+  // Note: Might fail on real hardware with some null-modem cables
   uart.check_connected().expect("should have physically connected receiver");
   uart.send_bytes_exact(b"hello world!");
 }