From 5a00edf5e8db2ea9239ae1a4e1681a4b6636c0c8 Mon Sep 17 00:00:00 2001
From: Jeremy Wall <jeremy@marzhillstudios.com>
Date: Wed, 2 Feb 2022 22:48:32 -0500
Subject: [PATCH] Update readme and docs

---
 README.md     | 23 ++++++++++++++++++++++-
 src/lib.rs    |  5 ++++-
 src/packet.rs | 35 ++++++++++++++++++++++++++++++++++-
 src/socket.rs |  5 ++++-
 4 files changed, 64 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 6b94252..eefcbd0 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,22 @@
-# ICMP Sockets for both IPv4 and IPv6
\ No newline at end of file
+# ICMP Sockets for both IPv4 and IPv6
+
+An implementation of ICMP Sockets for both IPv4 and IPv6.
+
+Sockets can be created from IP addresses. IPv4 addresses will construct ICMP4 sockets. IPv6 will construct ICMP6 sockets.
+
+```rust
+let parsed_addr = "127.0.0.1".parse::<Ipv4Addr>().unwrap();
+let socket = IcmpSocket4::try_from(parsed_addr).unwrap();
+```
+
+It can construct and parse the common ICMP packets for both ICMP4 and ICMP6.
+
+```rust
+let packet4 = Icmpv4Packet::with_echo_request(42, 1, "payload".to_bytes());
+let packet6 = Icmpv6Packet::with_echo_request(42, 1, "payload".to_bytes());
+)
+```
+
+# API Documentation
+
+https://docs.rs/icmp-socket/0.1.1
\ No newline at end of file
diff --git a/src/lib.rs b/src/lib.rs
index 004be81..38d159d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -11,7 +11,10 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-
+//! An ICMP socket library that tries to be ergonomic to use.
+//!
+//! The standard ping examples for both Ipv6 and IPv4 are in the examples
+//! directory.
 pub mod packet;
 pub mod socket;
 
diff --git a/src/packet.rs b/src/packet.rs
index 388d332..4e5841d 100644
--- a/src/packet.rs
+++ b/src/packet.rs
@@ -11,6 +11,38 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
+//! Packet parsing and construction.
+//!
+//! Where possible we use traits to support a common API for constructing the
+//! ICMPv4 and ICMPv6 versions of the packets.
+//!
+//! Both packet types can be constructed from a slice: `&[u8]` via the [`TryFrom`] trait.
+//!
+//! # Examples
+//!
+//! Constructing an ICMPv4 echo request.
+//! ```
+//! # use icmp_socket::packet::*;
+//! let packet = Icmpv4Packet::with_echo_request(
+//!     42, // An identifier so you can recognize responses to your own packets.
+//!     0, // the first echo request packet in our sequence.
+//!     "a payload big enough to matter".as_bytes().to_vec()
+//! ).unwrap();
+//! ```
+//!
+//! Parsing an ICMPv4 packet from a byte buffer.
+//! ```
+//! # use icmp_socket::packet::*;
+//! use std::convert::TryFrom;
+//! # let packet = Icmpv4Packet::with_echo_request(
+//! #     42, // An identifier so you can recognize responses to your own packets.
+//! #     0, // the first echo request packet in our sequence.
+//! #     "a payload big enough to matter".as_bytes().to_vec()
+//! # ).unwrap();
+//! # let mut byte_buffer = vec![0; 20];
+//! # byte_buffer.extend(packet.get_bytes(true)); // convert a packet to bytes with a checksum.
+//! let parsed_packet = Icmpv4Packet::try_from(byte_buffer.as_slice()).unwrap();
+//! ```
 use std::convert::TryFrom;
 
 use byteorder::{BigEndian, ByteOrder};
@@ -54,6 +86,7 @@ pub trait WithEchoRequest {
 }
 
 /// Construct a packet for Echo Reply messages.
+/// This packet type is really only used for the ICMPv6 protocol.
 pub trait WithEchoReply {
     type Packet;
 
@@ -669,7 +702,7 @@ pub struct Icmpv4Packet {
 }
 
 impl Icmpv4Packet {
-    /// Parse an Icmpv4Packet from bytes.
+    /// Parse an Icmpv4Packet from bytes including the IPv4 header.
     pub fn parse<B: AsRef<[u8]>>(bytes: B) -> Result<Self, PacketParseError> {
         let mut bytes = bytes.as_ref();
         let mut packet_len = bytes.len();
diff --git a/src/socket.rs b/src/socket.rs
index 0fd9f31..1aa6608 100644
--- a/src/socket.rs
+++ b/src/socket.rs
@@ -11,7 +11,10 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-
+//! ICMP Socket implementations for both ICMP4 and ICMP6 protocols.
+//!
+//! There is a common IcmpSocket trait implemented for both the v4 and v6 protocols.
+//! The socket is associated to both an address type and packet type.
 use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
 use std::{
     convert::{Into, TryFrom, TryInto},