From 585535d0a0f88852945ae6f91644c4209e9fa28d Mon Sep 17 00:00:00 2001
From: Alex Helfet <alex.helfet@gmail.com>
Date: Fri, 22 Dec 2017 13:41:02 +0000
Subject: [PATCH] Documentation.

---
 Cargo.toml |  2 +-
 README.md  |  3 +--
 src/lib.rs | 15 ++++++++++-----
 3 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index ee6274e..1bc872d 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "framed"
 version = "0.1.0"
-description = "Send and receive frames (arrays of bytes of varied length) over streams of bytes."
+description = "Send and receive slices of bytes over lossy streams of bytes."
 authors = ["Alex Helfet <alex.helfet@gmail.com>"]
 categories = ["embedded", "encoding", "network-programming"]
 keywords = ["no_std", "networking", "datalink", "protocol", "embedded"]
diff --git a/README.md b/README.md
index d020431..47b031b 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,6 @@
 # `framed`
 
-Rust crate to send and receive frames (arrays of bytes of varied length)
-over streams of bytes.
+Rust crate to send and receive slices of bytes over lossy streams of bytes.
 
 See [rustdoc on docs.rs](https://docs.rs/crate/framed)
 
diff --git a/src/lib.rs b/src/lib.rs
index ba40453..b6c0bdc 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,19 +1,24 @@
-//! Sending and receiving frames (arrays of bytes of varied length)
-//! over streams of bytes.
+//! Send and receive slices of bytes over lossy streams of bytes.
 //!
 //! Conforming to / inspired by the [data link layer][dll] or layer 2
 //! in the OSI networking model, this module enables sending slices of
-//! bytes of definite length over an underlying transport that only
-//! supports sending an unstructured stream of bytes (a [physical
+//! bytes of definite length over an underlying lossy transport that
+//! only supports sending an unstructured stream of bytes (a [physical
 //! layer][pl], such as ITM, UART or SPI).
 //!
 //! [dll]: https://en.wikipedia.org/wiki/Data_link_layer
 //! [pl]: https://en.wikipedia.org/wiki/Physical_layer
 //!
+//! The transport may corrupt the stream by dropping or modifying some
+//! bytes en route. When the transport returns corrupt data the
+//! decoder may return errors or corrupted payloads, but if the
+//! transport starts operating without losses again the decoder should
+//! return new uncorrupted frames.
+//!
 //! ## Encoding
 //!
 //! Currently the encoding is:
-//! * The frame [COBS]-encoded to remove bytes equal to zero
+//! * The payload [COBS]-encoded to remove bytes equal to zero
 //! * A terminating zero byte.
 //! [COBS]: https://en.wikipedia.org/wiki/Consistent_Overhead_Byte_Stuffing
 //!