From 19a160923889cb9239c34789103509b020576064 Mon Sep 17 00:00:00 2001
From: Astro <astro@spaceboyz.net>
Date: Mon, 18 Mar 2019 21:41:51 +0100
Subject: [PATCH] doc

---
 src/main.rs   |  5 +++++
 src/net.rs    | 12 ++++++++++--
 src/server.rs |  4 ++++
 src/timer.rs  |  7 +++++--
 4 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/src/main.rs b/src/main.rs
index ee851e2..1302f0a 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -33,6 +33,10 @@ mod timer;
 mod led;
 use led::Led;
 
+/// Interval at which to sample the ADC input and broadcast to all
+/// clients.
+///
+/// This should be a multiple of the `TIMER_RATE`.
 const OUTPUT_INTERVAL: u32 = 1000;
 
 #[cfg(not(feature = "semihosting"))]
@@ -55,6 +59,7 @@ fn init_log() {
     init(logger).expect("set logger");
 }
 
+/// Initialization and main loop
 #[entry]
 fn main() -> ! {
     init_log();
diff --git a/src/net.rs b/src/net.rs
index d485c64..05933e2 100644
--- a/src/net.rs
+++ b/src/net.rs
@@ -21,8 +21,11 @@ static mut TX_RING: Option<[RingEntry<TxDescriptor>; 2]> = None;
 // TODO: generate one from device id
 const SRC_MAC: [u8; 6] = [0x00, 0x00, 0xDE, 0xAD, 0xBE, 0xEF];
 
+/// Interrupt pending flag: set by the `ETH` interrupt handler, should
+/// be cleared before polling the interface.
 static NET_PENDING: Mutex<RefCell<bool>> = Mutex::new(RefCell::new(false));
 
+/// Run callback `f` with ethernet driver and TCP/IP stack
 pub fn run<F>(nvic: &mut NVIC, ethernet_mac: ETHERNET_MAC, ethernet_dma: ETHERNET_DMA, f: F)
 where
     F: FnOnce(EthernetInterface<&mut stm32_eth::Eth<'static, 'static>>),
@@ -33,12 +36,14 @@ where
     let tx_ring = unsafe {
         TX_RING.get_or_insert(Default::default())
     };
+    // Ethernet driver
     let mut eth_dev = Eth::new(
         ethernet_mac, ethernet_dma,
         &mut rx_ring[..], &mut tx_ring[..]
     );
     eth_dev.enable_interrupt(nvic);
 
+    // IP stack
     let local_addr = IpAddress::v4(192, 168, 69, 3);
     let mut ip_addrs = [IpCidr::new(local_addr, 24)];
     let mut neighbor_storage = [None; 16];
@@ -53,8 +58,8 @@ where
     f(iface);
 }
 
-/// Wake up from `wfi()`, clear interrupt flags,
-/// and TODO: set pending flag
+/// Potentially wake up from `wfi()`, set the interrupt pending flag,
+/// clear interrupt flags.
 #[interrupt]
 fn ETH() {
     cortex_m::interrupt::free(|cs| {
@@ -66,11 +71,14 @@ fn ETH() {
     stm32_eth::eth_interrupt_handler(&p.ETHERNET_DMA);
 }
 
+/// Has an interrupt occurred since last call to `clear_pending()`?
 pub fn is_pending(cs: &CriticalSection) -> bool {
     *NET_PENDING.borrow(cs)
         .borrow()
 }
 
+/// Clear the interrupt pending flag before polling the interface for
+/// data.
 pub fn clear_pending(cs: &CriticalSection) {
     *NET_PENDING.borrow(cs)
         .borrow_mut() = false;
diff --git a/src/server.rs b/src/server.rs
index 76f2266..b1080f8 100644
--- a/src/server.rs
+++ b/src/server.rs
@@ -8,6 +8,9 @@ use smoltcp::{
 
 
 const TCP_PORT: u16 = 23;
+/// Number of server sockets and therefore concurrent client
+/// sessions. Many data structures in `Server::run()` correspond to
+/// this const.
 const SOCKET_COUNT: usize = 8;
 
 const TCP_RX_BUFFER_SIZE: usize = 2048;
@@ -105,6 +108,7 @@ impl<'a, 'b> Server<'a, 'b> {
     }
 }
 
+/// Reusing the `fmt::Write` trait just for `write!()` convenience
 impl<'a, 's> fmt::Write for Server<'a, 's> {
     /// Write to all connected clients
     fn write_str(&mut self, slice: &str) -> fmt::Result {
diff --git a/src/timer.rs b/src/timer.rs
index 3592a79..98e3505 100644
--- a/src/timer.rs
+++ b/src/timer.rs
@@ -8,18 +8,20 @@ use stm32f4xx_hal::{
     stm32::SYST,
 };
 
-/// rate in Hz
+/// Rate in Hz
 const TIMER_RATE: u32 = 10;
-/// interval duration in milliseconds
+/// Interval duration in milliseconds
 const TIMER_DELTA: u32 = 1000 / TIMER_RATE;
 /// Elapsed time in milliseconds
 static TIMER_MS: Mutex<RefCell<u32>> = Mutex::new(RefCell::new(0));
 
+/// Setup SysTick exception
 pub fn setup(syst: SYST, clocks: Clocks) {
     let mut timer = Timer::syst(syst, TIMER_RATE.hz(), clocks);
     timer.listen(TimerEvent::TimeOut);
 }
 
+/// SysTick exception (Timer)
 #[exception]
 fn SysTick() {
     cortex_m::interrupt::free(|cs| {
@@ -28,6 +30,7 @@ fn SysTick() {
     });
 }
 
+/// Obtain current time in milliseconds
 pub fn now() -> MilliSeconds {
     let ms = cortex_m::interrupt::free(|cs| {
         *TIMER_MS.borrow(cs)