Merge pull request #6 from mozilla/doc-note

doc: Add an example

Author: larseggert

.github/workflows/check.yml

@@ -94,10 +94,9 @@ jobs:
             # no memory and leak sanitizer support yet
             SANITIZERS="address thread"
           fi
-
           for sanitizer in $SANITIZERS; do
             echo "Running tests with $sanitizer sanitizer..."
-            RUSTFLAGS="-Z sanitizer=$sanitizer" cargo +nightly test -Z build-std --target "$TARGET"
+            RUSTFLAGS="-Z sanitizer=$sanitizer" RUSTDOCFLAGS="-Z sanitizer=$sanitizer" cargo +nightly test -Z build-std --target "$TARGET"
           done
 
       - name: Check formatting

.rustfmt.toml

@@ -0,0 +1,13 @@
+# Keep in sync with `Cargo.toml` `edition`.
+#
+# `rustfmt` envoked not through `cargo fmt` but directly does not pick up Rust
+# edition in `Cargo.toml`. Thus duplicate here.
+edition = "2021"
+
+comment_width=100
+wrap_comments=true
+
+imports_granularity="Crate"
+group_imports="StdExternalCrate"
+
+format_code_in_doc_comments=true

src/lib.rs

@@ -20,7 +20,20 @@ fn default_result<T>() -> Result<T, Error> {
     ))
 }
 
-/// Return the MTU of the interface that is used to reach the given remote socket address.
+/// Return the maximum transmission unit (MTU) of the local network interface towards the
+/// destination [`SocketAddr`] given in `remote`.
+///
+/// The returned MTU may exceed the maximum IP packet size of 65,535 bytes on some
+/// platforms for some remote destinations. (For example, loopback destinations on
+/// Windows.)
+///
+/// # Examples
+///
+/// ```
+/// let saddr = "127.0.0.1:443".parse().unwrap();
+/// let mtu = mtu::get_interface_mtu(&saddr).unwrap();
+/// println!("MTU towards {:?} is {}", saddr, mtu);
+/// ```
 ///
 /// # Errors
 ///