From 22c5fd48320b61dba27835db6f8512d8797ec554 Mon Sep 17 00:00:00 2001
From: "Dustin C. Hatch" <dustin@hatch.name>
Date: Sat, 29 Sep 2018 12:11:10 -0500
Subject: [PATCH] Add rustdoc comments

This commit adds documentation comments to the public API. In order for
`cargo doc` to build the documentation site, though, the crate must be a
library, so the `lib.rs` is needed to expose the necessary bits.
---
 src/lib.rs   | 19 +++++++++++++++++++
 src/mac.rs   | 17 +++++++++++++++++
 src/magic.rs | 15 +++++++++++++++
 3 files changed, 51 insertions(+)
 create mode 100644 src/lib.rs

diff --git a/src/lib.rs b/src/lib.rs
new file mode 100644
index 0000000..b921a1d
--- /dev/null
+++ b/src/lib.rs
@@ -0,0 +1,19 @@
+//! Send Wake-on-LAN magic packets to wake sleeping machines
+//!
+//! This create provides a library and command-line interface for building
+//! wake-on-LAN magic packets and sending them to network destinations.
+//!
+//! # Examples
+//!
+//! Basic usage:
+//!
+//! ```
+//! use wakeonlan::{mac, magic};
+//!
+//! let mac = mac::MacAddress::from_string("aa:bb:cc:dd:ee:ff").unwrap();
+//! let packet = magic::MagicPacket::new(&mac);
+//! packet.send().unwrap();
+//! ```
+
+pub mod mac;
+pub mod magic;
diff --git a/src/mac.rs b/src/mac.rs
index 1733b70..7b32f51 100644
--- a/src/mac.rs
+++ b/src/mac.rs
@@ -1,11 +1,21 @@
+//! MAC address parsing
+//!
+//! This module provides tools for parsing and using MAC addresses. MAC
+//! addresses are used as physical device addresses in Ethernet and other
+//! layer-2 networking protocols.
+
 use std::error;
 use std::fmt;
 use std::num;
 
 
+/// Error returned when attempting to parse a MAC address
 #[derive(Debug)]
 pub enum ParseError {
+    /// The input contained an invalid numeric value
     Value(num::ParseIntError),
+
+    /// The input was not correctly formatted
     Format,
 }
 
@@ -37,6 +47,7 @@ impl error::Error for ParseError {
 }
 
 
+/// MAC address
 #[derive(Debug)]
 pub struct MacAddress {
     addr: [u8; 6],
@@ -44,6 +55,11 @@ pub struct MacAddress {
 
 
 impl MacAddress {
+
+    /// Parse a MAC address from a string
+    ///
+    /// This method parses a 48-bit MAC address from a standard string of
+    /// six hexadecimal octets separated by colons or hyphens.
     pub fn from_string(s: &str) -> Result<Self, ParseError> {
         let split: Result<Vec<_>, _> = s.split(|c| c == ':' || c == '-')
             .map(|b| u8::from_str_radix(b, 16))
@@ -62,6 +78,7 @@ impl MacAddress {
         }
     }
 
+    /// Get the MAC address as an array of bytes
     pub fn as_bytes(&self) -> &[u8; 6] {
         &self.addr
     }
diff --git a/src/magic.rs b/src/magic.rs
index 47922d5..f7e5262 100644
--- a/src/magic.rs
+++ b/src/magic.rs
@@ -1,22 +1,37 @@
+//! Wake-On-LAN Magic Packets
+//!
+//! This module contains tools for creating and sending WOL magic packets.
+
 use std::io;
 use std::net;
 use mac;
 
 
+/// Magic packet for a specific MAC address
 pub struct MagicPacket<'a> {
     mac: &'a mac::MacAddress,
 }
 
 
 impl<'a> MagicPacket<'a> {
+
+    /// Create a new magic packet the given MAC address
     pub fn new(mac: &'a mac::MacAddress) -> Self {
         MagicPacket { mac }
     }
 
+    /// Send the magic packet
+    ///
+    /// This method sends the magic packet to the default destination: the
+    /// subnet-directed broadcast on UDP port 9.
     pub fn send(&self) -> io::Result<usize> {
         self.send_to("255.255.255.255:9")
     }
 
+    /// Send the magic packet to a specific destination
+    ///
+    /// This method sends the magic packet to the given destination address
+    /// and UDP port.
     pub fn send_to<A: net::ToSocketAddrs>(&self, addr: A) -> io::Result<usize> {
         let socket = net::UdpSocket::bind("0.0.0.0:0")?;
         socket.set_broadcast(true)?;