Documentation!

src/lib.rs

@@ -1,8 +1,73 @@
 #![cfg_attr(feature = "use_alloc", feature(alloc))]
 #![no_std]
 
-extern crate byteorder;
+//! The _smoltcp_ library is built in a layered structure, with the layers corresponding
+//! to the levels of API abstraction. Only the highest layers would be used by a typical
+//! application; however, the goal of _smoltcp_ is not just to provide a simple interface
+//! for writing applications but also to be a toolbox of networking primitives, so
+//! every layer is fully exposed and documented.
+//!
+//! 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,
+//! 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
+//! use sockets together with a network interface.
+//!
+//! # The interface layer
+//! The interface layer APIs are provided in the module [iface](iface/index.html); currently,
+//! Ethernet interface is provided.
+//!
+//! The interface layer handles the control messages, physical addressing and neighbor discovery.
+//! It owns the sockets and routes packets to and from them.
+//!
+//! # The physical layer
+//! The physical layer APIs are provided in the module [phy](phy/index.html); currently,
+//! raw socket and TAP interface are provided. In addition, two "middleware" interfaces
+//! are provided: the _tracer device_, which prints a human-readable representation of packets,
+//! and the _fault injector device_, which randomly introduces errors into the transmitted
+//! and received packet sequences.
+//!
+//! The physical layer handles interaction with a platform-specific network device.
+//!
+//! # The wire layers
+//! Unlike the higher layers, the wire layer APIs will not be used by a typical application.
+//! They however are the bedrock of _smoltcp_, and everything else is built on top of them.
+//!
+//! The wire layer APIs are designed by the principle "make illegal states irrepresentable".
+//! If a wire layer object can be constructed, then it can also be parsed from or emitted to
+//! a lower level.
+//!
+//! The wire layer APIs also provide _tcpdump_-like pretty printing.
+//!
+//! ## The representation layer
+//! The representation layer APIs are provided in the module [wire](wire/index.html); currently,
+//! Ethernet, ARP, generic IP, IPv4, ICMPv4, TCP and UDP packet representations are provided.
+//!
+//! The representation layer exists to reduce the state space of raw packets. Raw packets
+//! may be nonsensical in a multitude of ways: invalid checksums, impossible combinations of flags,
+//! pointers to fields out of bounds, meaningless options... Representations shed all that,
+//! as well as any features not supported by _smoltcp_.
+//!
+//! ## The packet layer
+//! The packet layer APIs are also provided in the module [wire](wire/index.html); currently,
+//! Ethernet, ARP, IPv4, ICMPv4, TCP and UDP packet representations are provided.
+//!
+//! The packet layer exists to provide a more structured way to work with packets than
+//! treating them as sequences of octets. It makes no judgement as to content of the packets,
+//! 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.
 
+extern crate byteorder;
 #[cfg(any(test, feature = "use_std"))]
 #[macro_use]
 extern crate std;