Docsrs labels (#380)

* Make docs.rs source view generate links to definitions.

* Disable default features for eui48 crate so it will no longer pull in rustc-serialize, which has had a history of causing builds to print deprecation warnings.

* Revert "Disable default features for eui48 crate so it will no longer pull in rustc-serialize, which has had a history of causing builds to print deprecation warnings."

This reverts commit 36138ca.

* Support `cfg()` labels in documentation generated on docs.rs.

This is a nightly-only feature, and can used locally by setting
`RUSTFLAGS="--cfg docsrs"` and `RUSTDOCFLAGS="--cfg docsrs"` and then
generating the documentation using `cargo +nightly doc --all-features`.

Generating documentation using stable `cargo doc` (without the
`--cfg docsrs`) should work just as normal.

* Intructions on how to build doc with nightly labels.

---------

Co-authored-by: Jan Danielsson <jan@void>

Cargo.toml

@@ -109,4 +109,4 @@ required-features = ["capture-stream"]
 
 [package.metadata.docs.rs]
 all-features = true
-rustdoc-args = ["--generate-link-to-definition"]
+rustdoc-args = ["--cfg", "docsrs", "--generate-link-to-definition"]

README.md

@@ -104,6 +104,18 @@ Some dependencies no longer support our chosen MSRV. Since many crates do not co
 
 [Discuss the MSRV](https://github.com/rust-pcap/pcap/discussions/240).
 
+# Documentation labels
+
+Generating documentation with `cfg` labels requires a nightly toolchain.  To
+use this feature set the environment variables:
+
+```
+RUSTFLAGS="--cfg docsrs"
+RUSTDOCFLAGS="--cfg docsrs"
+```
+
+Then generate the documentation using `cargo +nightly doc --all-features`.
+
 # License
 
 Licensed under either of

src/capture/mod.rs

@@ -1,6 +1,7 @@
 pub mod activated;
 pub mod inactive;
 #[cfg(all(not(windows), feature = "capture-stream"))]
+#[cfg_attr(docsrs, doc(cfg(all(not(windows), feature = "capture-stream"))))]
 pub mod selectable;
 
 use std::{

src/lib.rs

@@ -58,6 +58,8 @@
 //! }
 //! ```
 
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 use std::ffi::{self, CStr};
 use std::fmt;
 
@@ -88,11 +90,13 @@ pub type TstampType = TimestampType;
 mod raw;
 
 #[cfg(windows)]
+#[cfg_attr(docsrs, doc(cfg(windows)))]
 pub mod sendqueue;
 
 #[cfg(feature = "capture-stream")]
 mod stream;
 #[cfg(feature = "capture-stream")]
+#[cfg_attr(docsrs, doc(cfg(feature = "capture-stream")))]
 pub use stream::PacketStream;
 
 /// An error received from pcap

src/sendqueue/mod.rs

@@ -1,3 +1,5 @@
+//! Utilities for sending batches of packets.
+
 #[cfg(windows)]
 pub mod windows;
 #[cfg(windows)]

src/sendqueue/windows.rs

@@ -14,10 +14,20 @@ use crate::{
     raw, Error,
 };
 
+/// Representation of a batch of packets that can be transferred in a single call using
+/// [`SendQueue::transmit()`].
 pub struct SendQueue(NonNull<raw::pcap_send_queue>);
 
+/// Indicate whether to send packets as quickly as possible or delay the relative amount of time
+/// between packet header timestamps between packet transmissions.
 pub enum SendSync {
+    /// Ignore timestamps; send packets as quickly as possible.
     Off = 0,
+
+    /// Use the time difference between packets to delay between packet transmissions.
+    ///
+    /// # Notes
+    /// The internal (n/win)pcap implementations may implement the delay as a busy-wait loop.
     On = 1,
 }