renet
/
renet
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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.
v0.7.x
Dan Robertson 2018-01-05 14:38:23 -05:00 committed by whitequark
parent 22b048c225
commit b653a6e421
9 changed files with 102 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
src/iface/mod.rs
View File

@ -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;

2
src/iface/neighbor.rs
View File

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

5
src/lib.rs
View File

@ -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",

38
src/phy/mod.rs
View File

@ -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};

23
src/socket/mod.rs
View File

@ -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;

5
src/socket/tcp.rs
View File

@ -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,

11
src/storage/mod.rs
View File

@ -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;

91
src/wire/mod.rs
View File

@ -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")]
# {

19
src/wire/pretty_print.rs
View File

@ -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![