Touch up docs, use intra-doc-links

.github/workflows/ci.yml

@@ -9,6 +9,7 @@ on:
 env:
   CARGO_TERM_COLOR: always
   RUSTFLAGS: --deny warnings
+  RUSTDOCFLAGS: --deny warnings
 
 jobs:
   test:

rubble/src/att/mod.rs

@@ -26,8 +26,6 @@
 //! by indicating the *Group End Handle* to the client, which is the handle of the last attribute in
 //! the group. The *Group End Handle* isn't known by the ATT server and must be provided by the
 //! higher-level protocol (GATT).
-//!
-//! [`Handle`]: struct.Handle.html
 
 mod handle;
 mod pdus;

rubble/src/att/uuid.rs

@@ -3,7 +3,7 @@ use core::{cmp::PartialEq, fmt};
 
 /// ATT protocol UUID (either a 16 or a 128-bit UUID).
 ///
-/// 32-bit UUIDs are not supported by ATT are must be converted to 128-bit UUIDs.
+/// 32-bit UUIDs are not supported by ATT and must be converted to 128-bit UUIDs.
 #[derive(Copy, Clone, Eq)]
 pub enum AttUuid {
     Uuid16(Uuid16),

rubble/src/beacon.rs

@@ -53,7 +53,7 @@ impl Beacon {
     }
 }
 
-/// Callback for the `BeaconScanner`.
+/// Callback for the [`BeaconScanner`].
 pub trait ScanCallback {
     /// Called when a beacon is received and has passed the configured device address filter.
     ///

rubble/src/ecdh/mod.rs

@@ -13,12 +13,7 @@
 //!   [*ring*][ring] library to provide the operations. Note that *ring* does not support
 //!   `#![no_std]` operation, so this is mostly useful for tests and other non-embedded usage.
 //!
-//! [`security`]: ../security/index.html
-//! [`EcdhProvider`]: trait.EcdhProvider.html
-//! [`P256Provider`]: struct.P256Provider.html
-//! [`P256SecretKey`]: struct.P256SecretKey.html
-//! [`RingProvider`]: struct.RingProvider.html
-//! [`RingSecretKey`]: struct.RingSecretKey.html
+//! [`security`]: crate::security
 //! [ring]: https://github.com/briansmith/ring
 //! [`p256`]: https://docs.rs/p256
 

rubble/src/gatt/mod.rs

@@ -82,7 +82,7 @@ impl AttributeProvider for BatteryServiceAttrs {
 
 /// A demo `AttributeProvider` that will enumerate as a *Midi Service*.
 ///
-/// Also refer to https://www.midi.org/specifications-old/item/bluetooth-le-midi
+/// Also refer to <https://www.midi.org/specifications-old/item/bluetooth-le-midi>.
 pub struct MidiServiceAttrs {
     attributes: [Attribute<&'static [u8]>; 4],
 }

rubble/src/l2cap/mod.rs

@@ -18,7 +18,6 @@
 //! Bluetooth SIG or allocated dynamically for use with the Service Discovery Protocol (SDP). The
 //! preallocated numbers are hosted online [here][l2c].
 //!
-//! [`Channel`]: struct.Channel.html
 //! [l2c]: https://www.bluetooth.com/specifications/assigned-numbers/logical-link-control
 
 mod signaling;

rubble/src/lib.rs

@@ -10,14 +10,10 @@
 //!
 //! The only part that interacts directly with platform-specific interfaces is [`link`], Rubble's
 //! BLE Link-Layer implementation. You have to provide it with a few hardware-specific services:
-//! * A microsecond-precision [`Timer`].
-//! * A [`Transmitter`] that can send data and advertising channel packets.
-//! * A processor for `link::Cmd`, which tells the support code when to call Rubble's functions
+//! * A microsecond-precision [`Timer`][time::Timer].
+//! * A [`Transmitter`][link::Transmitter] that can send data and advertising channel packets.
+//! * A processor for [`link::Cmd`], which tells the support code when to call Rubble's functions
 //!   again.
-//!
-//! [`link`]: link/index.html
-//! [`Timer`]: time/trait.Timer.html
-//! [`Transmitter`]: link/trait.Transmitter.html
 
 // We're `#[no_std]`, except when we're testing
 #![cfg_attr(not(test), no_std)]

rubble/src/link/advertising.rs

@@ -791,9 +791,6 @@ enum_with_unknown! {
     /// 4-bit PDU type in [`Header`].
     ///
     /// For more details, see [`PduBuf`].
-    ///
-    /// [`Header`]: struct.Header.html
-    /// [`PduBuf`]: struct.PduBuf.html
     #[derive(Debug, PartialEq, Eq)]
     pub enum PduType(u8) {
         /// Connectable undirected advertising event (`ADV_IND`).

rubble/src/link/comp_id.rs

@@ -1,4 +1,4 @@
-//! Company identifier implementation
+//! Company identifiers.
 
 use core::fmt;
 

rubble/src/link/llcp.rs

@@ -413,7 +413,7 @@ enum_with_unknown! {
 enum_with_unknown! {
     /// Enumeration of all possible `VersNr` for `LL_VERSION_IND` PDUs.
     ///
-    /// According to https://www.bluetooth.com/specifications/assigned-numbers/link-layer
+    /// According to <https://www.bluetooth.com/specifications/assigned-numbers/link-layer>.
     #[derive(Debug, Copy, Clone, PartialEq, Eq, defmt::Format)]
     pub enum VersionNumber(u8) {
         V4_0 = 6,

rubble/src/link/mod.rs

@@ -225,7 +225,7 @@ enum State<C: Config> {
 /// Implementation of the real-time BLE Link-Layer logic.
 ///
 /// Users of this struct must provide an interface to the platform's hardware by implementing
-/// `HardwareInterface`.
+/// [`Config`].
 pub struct LinkLayer<C: Config> {
     dev_addr: DeviceAddress,
     state: State<C>,

rubble/src/link/queue.rs

@@ -11,13 +11,6 @@
 //!   splitting a [`PacketQueue`].
 //! * The [`SimpleQueue`], [`SimpleProducer`] and [`SimpleConsumer`] types, a minimal implementation
 //!   of the queue interface defined by [`PacketQueue`], [`Producer`] and [`Consumer`].
-//!
-//! [`PacketQueue`]: trait.PacketQueue.html
-//! [`Producer`]: trait.Producer.html
-//! [`Consumer`]: trait.Consumer.html
-//! [`SimpleQueue`]: struct.SimpleQueue.html
-//! [`SimpleProducer`]: struct.SimpleProducer.html
-//! [`SimpleConsumer`]: struct.SimpleConsumer.html
 
 use crate::link::data::{self, Llid};
 use crate::link::{MIN_DATA_PAYLOAD_BUF, MIN_DATA_PDU_BUF};
@@ -27,7 +20,7 @@ use heapless::spsc;
 /// A splittable SPSC queue for data channel PDUs.
 ///
 /// Implementations of this trait must fit at least one data channel packet with a total size of
-/// `MIN_DATA_PDU_BUF` bytes (header and payload).
+/// [`MIN_DATA_PDU_BUF`] bytes (header and payload).
 pub trait PacketQueue {
     /// Producing (writing) half of the queue.
     type Producer: Producer;
@@ -120,21 +113,21 @@ pub trait Consumer {
 
     /// Passes the next raw packet in the queue to a closure.
     ///
-    /// The closure returns a `Consume` value to indicate whether the packet should remain in the
+    /// The closure returns a [`Consume`] value to indicate whether the packet should remain in the
     /// queue or be removed.
     ///
-    /// If the queue is empty, `Error::Eof` is returned.
+    /// If the queue is empty, [`Error::Eof`] is returned.
     fn consume_raw_with<R>(
         &mut self,
         f: impl FnOnce(data::Header, &[u8]) -> Consume<R>,
     ) -> Result<R, Error>;
 
     /// Passes the next packet in the queue to a closure.
     ///
-    /// The closure returns a `Consume` value to indicate whether the packet should remain in the
+    /// The closure returns a [`Consume`] value to indicate whether the packet should remain in the
     /// queue or be removed.
     ///
-    /// If the queue is empty, `Error::Eof` is returned.
+    /// If the queue is empty, [`Error::Eof`] is returned.
     fn consume_pdu_with<R>(
         &mut self,
         f: impl FnOnce(data::Header, data::Pdu<'_, &[u8]>) -> Consume<R>,
@@ -213,10 +206,8 @@ impl<T> Consume<T> {
 ///
 /// This type is compatible with thumbv6 cores, which lack atomic operations that might be needed
 /// for other queue implementations.
-///
-/// This queue also minimizes RAM usage: In addition to the raw buffer space, only minimal space is
-/// needed for housekeeping.
 pub struct SimpleQueue {
+    // FIXME this uses 2 PDUs worth of space, but should only use 1
     inner: spsc::Queue<[u8; MIN_DATA_PDU_BUF], 2>,
 }
 

rubble/src/time.rs

@@ -17,17 +17,17 @@ impl Duration {
     /// The duration of the interframe spacing between BLE packets.
     pub const T_IFS: Self = Duration(150);
 
-    /// Creates a `Duration` from a number of microseconds.
+    /// Creates a [`Duration`] from a number of microseconds.
     pub fn from_micros(micros: u32) -> Self {
         Duration(micros)
     }
 
-    /// Creates a `Duration` representing the given number of milliseconds.
+    /// Creates a [`Duration`] representing the given number of milliseconds.
     pub fn from_millis(millis: u16) -> Self {
         Duration(u32::from(millis) * 1_000)
     }
 
-    /// Creates a `Duration` representing a number of seconds.
+    /// Creates a [`Duration`] representing a number of seconds.
     pub fn from_secs(secs: u16) -> Self {
         Duration(u32::from(secs) * 1_000_000)
     }
@@ -143,14 +143,11 @@ impl defmt::Format for Duration {
 /// [`Timer`] instances (even when using the same implementation) are not compatible, and mixing
 /// them in operations causes unspecified results. [`Duration`]s are independent of the [`Timer`]
 /// implementation and thus can be mixed freely.
-///
-/// [`Duration`]: struct.Duration.html
-/// [`Timer`]: trait.Timer.html
 #[derive(Copy, Clone)]
 pub struct Instant(u32);
 
 impl Instant {
-    /// The maximum time between two `Instant`s that can be handled by `Instant::duration_since`.
+    /// The maximum time between two `Instant`s that can be handled by [`Instant::duration_since`].
     ///
     /// This is defined to be a value of a few minutes, intended to be sufficient for the BLE stack.
     pub const MAX_TIME_BETWEEN: Duration = Duration(1_000_000 * 60 * 5); // 5 minutes
@@ -176,16 +173,14 @@ impl Instant {
 
     /// Calculates the duration of time that has passed between `earlier` and `self`.
     ///
-    /// The maximum duration that can be calculated by this method is defined as `MAX_TIME_BETWEEN`.
-    /// Calling this method when the `Instant`s are further apart is an error and may panic. This is
-    /// done as a safeguard, since `Instant`s can wrap around, which can cause the result of this
-    /// function to be incorrect. It does not prevent that from happening, but makes unexpected
-    /// durations show up much earlier.
+    /// The maximum duration that can be calculated by this method is defined as
+    /// [`Instant::MAX_TIME_BETWEEN`]. Calling this method when the `Instant`s are further apart is
+    /// an error and may panic. This is done as a safeguard, since `Instant`s can wrap around,
+    /// which can cause the result of this function to be incorrect. It does not prevent that
+    /// from happening, but makes unexpected durations show up much earlier.
     ///
     /// Both `self` and `earlier` must have been created by the same [`Timer`], or the result of
     /// this function will be unspecified.
-    ///
-    /// [`Timer`]: trait.Timer.html
     pub fn duration_since(&self, earlier: Instant) -> Duration {
         let micros_passed = self.0.wrapping_sub(earlier.0);
         debug_assert!(
@@ -200,10 +195,8 @@ impl Instant {
     }
 }
 
-/// `Instant`s can be subtracted, which computes the `Duration` between the rhs and lhs using
+/// [`Instant`]s can be subtracted, which computes the [`Duration`] between the rhs and lhs using
 /// [`Instant::duration_since`].
-///
-/// [`Instant::duration_since`]: struct.Instant.html#method.duration_since
 impl Sub<Instant> for Instant {
     type Output = Duration;
 
@@ -212,7 +205,7 @@ impl Sub<Instant> for Instant {
     }
 }
 
-/// A `Duration` can be added to an `Instant`, moving the `Instant` forwards in time.
+/// A [`Duration`] can be added to an [`Instant`], moving the [`Instant`] forwards in time.
 impl Add<Duration> for Instant {
     type Output = Self;
 
@@ -227,7 +220,7 @@ impl AddAssign<Duration> for Instant {
     }
 }
 
-/// A `Duration` can be subtracted from an `Instant`, moving the `Instant` backwards in time.
+/// A [`Duration`] can be subtracted from an [`Instant`], moving the [`Instant`] backwards in time.
 impl Sub<Duration> for Instant {
     type Output = Self;
 
@@ -236,7 +229,7 @@ impl Sub<Duration> for Instant {
     }
 }
 
-/// Subtracts a `Duration` from `self`.
+/// Subtracts a [`Duration`] from `self`.
 impl SubAssign<Duration> for Instant {
     fn sub_assign(&mut self, d: Duration) {
         *self = *self - d;
@@ -281,9 +274,9 @@ impl fmt::Debug for Instant {
 ///
 /// This trait can also be implemented by a mock timer for testing.
 pub trait Timer {
-    /// Obtain the current time as an `Instant`.
+    /// Obtain the current time as an [`Instant`].
     ///
-    /// The `Instant`s returned by this function must never move backwards in time, except when the
-    /// underlying value wraps around.
+    /// The [`Instant`]s returned by this function must never move backwards in time, except when
+    /// the underlying value wraps around.
     fn now(&self) -> Instant;
 }