Fix documentation warnings.

- There are several warnings that are thrown when running `cargo doc`. Fix
  these warnings.
- Convert all module documentation to use /*! for consistency.

Author: dlrobertson

src/iface/mod.rs

@@ -1,7 +1,8 @@
-//! Network interface logic.
-//!
-//! The `iface` module deals with the *network interfaces*. It filters incoming frames,
-//! provides lookup and caching of hardware addresses, and handles management packets.
+/*! Network interface logic.
+
+The `iface` module deals with the *network interfaces*. It filters incoming frames,
+provides lookup and caching of hardware addresses, and handles management packets.
+*/
 
 mod neighbor;
 mod ethernet;

src/iface/neighbor.rs

@@ -32,13 +32,15 @@ pub(crate) enum Answer {
 /// # Examples
 ///
 /// On systems with heap, this cache can be created with:
+///
 /// ```rust
 /// use std::collections::BTreeMap;
 /// use smoltcp::iface::NeighborCache;
 /// let mut neighbor_cache = NeighborCache::new(BTreeMap::new());
 /// ```
 ///
 /// On systems without heap, use:
+///
 /// ```rust
 /// use smoltcp::iface::NeighborCache;
 /// let mut neighbor_cache_storage = [None; 8];

src/lib.rs

@@ -12,14 +12,12 @@
 //!
 //! When discussing networking stacks and layering, often the [OSI model][osi] is invoked.
 //! _smoltcp_ makes no effort to conform to the OSI model as it is not applicable to TCP/IP.
-//! [osi]: https://en.wikipedia.org/wiki/OSI_model
 //!
 //! # The socket layer
 //! The socket layer APIs are provided in the module [socket](socket/index.html); currently,
 //! raw, ICMP, TCP, and UDP sockets are provided. The socket API provides the usual primitives,
 //! but necessarily differs in many from the [Berkeley socket API][berk], as the latter was
 //! not designed to be used without heap allocation.
-//! [berk]: https://en.wikipedia.org/wiki/Berkeley_sockets
 //!
 //! The socket layer provides the buffering, packet construction and validation, and (for
 //! stateful sockets) the state machines, but it is interface-agnostic. An application must
@@ -69,6 +67,9 @@
 //! except where necessary to provide safe access to fields, and strives to implement every
 //! feature ever defined, to ensure that, when the representation layer is unable to make sense
 //! of a packet, it is still logged correctly and in full.
+//!
+//! [osi]: https://en.wikipedia.org/wiki/OSI_model
+//! [berk]: https://en.wikipedia.org/wiki/Berkeley_sockets
 
 /* XXX compiler bug
 #![cfg(not(any(feature = "socket-raw",

src/phy/mod.rs

@@ -1,23 +1,21 @@
-//! Access to networking hardware.
-//!
-//! The `phy` module deals with the *network devices*. It provides a trait
-//! for transmitting and receiving frames, [Device](trait.Device.html)
-//! and implementations of it:
-//!
-//!   * the [_loopback_](struct.Loopback.html), for zero dependency testing;
-//!   * _middleware_ [Tracer](struct.Tracer.html) and
-//!     [FaultInjector](struct.FaultInjector.html), to facilitate debugging;
-//!   * _adapters_ [RawSocket](struct.RawSocket.html) and
-//!     [TapInterface](struct.TapInterface.html), to transmit and receive frames
-//!     on the host OS.
-//!
-// https://github.com/rust-lang/rust/issues/38740
-//! <h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
-//!
-//! An implementation of the [Device](trait.Device.html) trait for a simple hardware
-//! Ethernet controller could look as follows:
-//!
-/*!
+/*! Access to networking hardware.
+
+The `phy` module deals with the *network devices*. It provides a trait
+for transmitting and receiving frames, [Device](trait.Device.html)
+and implementations of it:
+
+  * the [_loopback_](struct.Loopback.html), for zero dependency testing;
+  * _middleware_ [Tracer](struct.Tracer.html) and
+    [FaultInjector](struct.FaultInjector.html), to facilitate debugging;
+  * _adapters_ [RawSocket](struct.RawSocket.html) and
+    [TapInterface](struct.TapInterface.html), to transmit and receive frames
+    on the host OS.
+
+# Examples
+
+An implementation of the [Device](trait.Device.html) trait for a simple hardware
+Ethernet controller could look as follows:
+
 ```rust
 use smoltcp::Result;
 use smoltcp::phy::{self, DeviceCapabilities, Device};

src/socket/mod.rs

@@ -1,14 +1,15 @@
-//! Communication between endpoints.
-//!
-//! The `socket` module deals with *network endpoints* and *buffering*.
-//! It provides interfaces for accessing buffers of data, and protocol state machines
-//! for filling and emptying these buffers.
-//!
-//! The programming interface implemented here differs greatly from the common Berkeley socket
-//! interface. Specifically, in the Berkeley interface the buffering is implicit:
-//! the operating system decides on the good size for a buffer and manages it.
-//! The interface implemented by this module uses explicit buffering: you decide on the good
-//! size for a buffer, allocate it, and let the networking stack use it.
+/*! Communication between endpoints.
+
+The `socket` module deals with *network endpoints* and *buffering*.
+It provides interfaces for accessing buffers of data, and protocol state machines
+for filling and emptying these buffers.
+
+The programming interface implemented here differs greatly from the common Berkeley socket
+interface. Specifically, in the Berkeley interface the buffering is implicit:
+the operating system decides on the good size for a buffer and manages it.
+The interface implemented by this module uses explicit buffering: you decide on the good
+size for a buffer, allocate it, and let the networking stack use it.
+*/
 
 use core::marker::PhantomData;
 

src/socket/tcp.rs

@@ -13,8 +13,9 @@ use storage::{Assembler, RingBuffer};
 /// A TCP socket ring buffer.
 pub type SocketBuffer<'a> = RingBuffer<'a, u8>;
 
-/// The state of a TCP socket, according to [RFC 793][rfc793].
-/// [rfc793]: https://tools.ietf.org/html/rfc793
+/// The state of a TCP socket, according to [RFC 793].
+///
+/// [RFC 793]: https://tools.ietf.org/html/rfc793
 #[derive(Debug, PartialEq, Eq, Clone, Copy)]
 pub enum State {
     Closed,

src/storage/mod.rs

@@ -1,8 +1,9 @@
-//! Specialized containers.
-//!
-//! The `storage` module provides containers for use in other modules.
-//! The containers support both pre-allocated memory, without the `std`
-//! or `alloc` crates being available, and heap-allocated memory.
+/*! Specialized containers.
+
+The `storage` module provides containers for use in other modules.
+The containers support both pre-allocated memory, without the `std`
+or `alloc` crates being available, and heap-allocated memory.
+*/
 
 mod assembler;
 mod ring_buffer;

src/wire/mod.rs

@@ -1,50 +1,47 @@
-//! Low-level packet access and construction.
-//!
-//! The `wire` module deals with the packet *representation*. It provides two levels
-//! of functionality.
-//!
-//!  * First, it provides functions to extract fields from sequences of octets,
-//!    and to insert fields into sequences of octets. This happens `Packet` family of
-//!    structures, e.g. [EthernetFrame] or [Ipv4Packet].
-//!  * Second, in cases where the space of valid field values is much smaller than the space
-//!    of possible field values, it provides a compact, high-level representation
-//!    of packet data that can be parsed from and emitted into a sequence of octets.
-//!    This happens through the `Repr` family of structs and enums, e.g. [ArpRepr] or [Ipv4Repr].
-// https://github.com/rust-lang/rust/issues/38739
-//! </ul>
-//!
-//! [EthernetFrame]: struct.EthernetFrame.html
-//! [Ipv4Packet]: struct.Ipv4Packet.html
-//! [ArpRepr]: enum.ArpRepr.html
-//! [Ipv4Repr]: struct.Ipv4Repr.html
-//!
-//! The functions in the `wire` module are designed for use together with `-Cpanic=abort`.
-//!
-//! The `Packet` family of data structures guarantees that, if the `Packet::check_len()` method
-//! returned `Ok(())`, then no accessor or setter method will panic; however, the guarantee
-//! provided by `Packet::check_len()` may no longer hold after changing certain fields,
-//! which are listed in the documentation for the specific packet.
-//!
-//! The `Packet::new_checked` method is a shorthand for a combination of `Packet::new` and
-//! `Packet::check_len`.
-//! When parsing untrusted input, it is *necessary* to use `Packet::new_checked()`;
-//! so long as the buffer is not modified, no accessor will fail.
-//! When emitting output, though, it is *incorrect* to use `Packet::new_checked()`;
-//! the length check is likely to succeed on a zeroed buffer, but fail on a buffer
-//! filled with data from a previous packet, such as when reusing buffers, resulting
-//! in nondeterministic panics with some network devices but not others.
-//! The buffer length for emission is not calculated by the `Packet` layer.
-//!
-//! In the `Repr` family of data structures, the `Repr::parse()` method never panics
-//! as long as `Packet::new_checked()` (or `Packet::check_len()`) has succeeded, and
-//! the `Repr::emit()` method never panics as long as the underlying buffer is exactly
-//! `Repr::buffer_len()` octets long.
-//!
-//! # Examples
-//!
-//! To emit an IP packet header into an octet buffer, and then parse it back:
-//!
-/*!
+/*! Low-level packet access and construction.
+
+The `wire` module deals with the packet *representation*. It provides two levels
+of functionality.
+
+ * First, it provides functions to extract fields from sequences of octets,
+   and to insert fields into sequences of octets. This happens `Packet` family of
+   structures, e.g. [EthernetFrame] or [Ipv4Packet].
+ * Second, in cases where the space of valid field values is much smaller than the space
+   of possible field values, it provides a compact, high-level representation
+   of packet data that can be parsed from and emitted into a sequence of octets.
+   This happens through the `Repr` family of structs and enums, e.g. [ArpRepr] or [Ipv4Repr].
+
+[EthernetFrame]: struct.EthernetFrame.html
+[Ipv4Packet]: struct.Ipv4Packet.html
+[ArpRepr]: enum.ArpRepr.html
+[Ipv4Repr]: struct.Ipv4Repr.html
+
+The functions in the `wire` module are designed for use together with `-Cpanic=abort`.
+
+The `Packet` family of data structures guarantees that, if the `Packet::check_len()` method
+returned `Ok(())`, then no accessor or setter method will panic; however, the guarantee
+provided by `Packet::check_len()` may no longer hold after changing certain fields,
+which are listed in the documentation for the specific packet.
+
+The `Packet::new_checked` method is a shorthand for a combination of `Packet::new` and
+`Packet::check_len`.
+When parsing untrusted input, it is *necessary* to use `Packet::new_checked()`;
+so long as the buffer is not modified, no accessor will fail.
+When emitting output, though, it is *incorrect* to use `Packet::new_checked()`;
+the length check is likely to succeed on a zeroed buffer, but fail on a buffer
+filled with data from a previous packet, such as when reusing buffers, resulting
+in nondeterministic panics with some network devices but not others.
+The buffer length for emission is not calculated by the `Packet` layer.
+
+In the `Repr` family of data structures, the `Repr::parse()` method never panics
+as long as `Packet::new_checked()` (or `Packet::check_len()`) has succeeded, and
+the `Repr::emit()` method never panics as long as the underlying buffer is exactly
+`Repr::buffer_len()` octets long.
+
+# Examples
+
+To emit an IP packet header into an octet buffer, and then parse it back:
+
 ```rust
 # #[cfg(feature = "proto-ipv4")]
 # {

src/wire/pretty_print.rs

@@ -1,13 +1,12 @@
-//! Pretty-printing of packet representation.
-//!
-//! The `pretty_print` module provides bits and pieces for printing concise,
-//! easily human readable packet listings.
-//!
-//! # Example
-//!
-//! A packet can be formatted using the `PrettyPrinter` wrapper:
-//!
-/*!
+/*! Pretty-printing of packet representation.
+
+The `pretty_print` module provides bits and pieces for printing concise,
+easily human readable packet listings.
+
+# Example
+
+A packet can be formatted using the `PrettyPrinter` wrapper:
+
 ```rust
 use smoltcp::wire::*;
 let buffer = vec![