From d9f650fc6e723dabeccc800c16ca4d809f4bb94a Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@finalrewind.org>
Date: Sun, 31 Jan 2016 18:44:23 +0100
Subject: document Modem and System classes

---
 src/display.h |  8 ++++++--
 src/modem.h   | 33 +++++++++++++++++++++++++++++++++
 src/system.h  |  8 ++++++++
 3 files changed, 47 insertions(+), 2 deletions(-)

(limited to 'src')

diff --git a/src/display.h b/src/display.h
index c7cf5f8..e382a25 100644
--- a/src/display.h
+++ b/src/display.h
@@ -4,6 +4,10 @@
 #include <util/delay.h>
 #include <stdlib.h>
 
+/**
+ * Describes the type of an animation object. The Storage class reserves four
+ * bits for the animation type, so up to 16 types are supported.
+ */
 enum class AnimationType : uint8_t {
 	TEXT = 1,
 	FRAMES = 2
@@ -26,7 +30,7 @@ struct animation {
 	uint8_t length;
 
 	/**
-	 * * If mode == TEXT: Text scroll speed in columns per TODO
+	 * * If mode == AnimationType::TEXT: Text scroll speed in columns per TODO
 	 * * If mode == FRAMES: Frames per TODO
 	 */
 	uint8_t speed;
@@ -42,7 +46,7 @@ struct animation {
 	uint8_t direction;
 
 	/**
-	 * * If mode == TEXT: character array pointing to the
+	 * * If mode == AnimationType::TEXT: character array pointing to the
 	 *   animation text in standard ASCII format (+ special font chars)
 	 * * If mode == FRAMES: Frame array. Each element encodes
 	 *   a display column (starting with the leftmost one), each group of
diff --git a/src/modem.h b/src/modem.h
index 18273f0..ea308a7 100644
--- a/src/modem.h
+++ b/src/modem.h
@@ -22,6 +22,11 @@
 #define MODEM_PIN		PA0
 #define MODEM_DDR		DDRA
 
+/**
+ * Receive-only modem. Sets up a pin change interrupt on the modem pin
+ * and receives bytes using a simple protocol. Does not detect or correct
+ * transmission errors. Exposes a global modem object for convenience.
+ */
 class Modem {
 	private:
 		uint8_t buffer_head;
@@ -30,10 +35,38 @@ class Modem {
 		void buffer_put(const uint8_t c);
 	public:
 		Modem() {};
+
+		/**
+		 * Checks if there are unprocessed bytes in the modem receive buffer.
+		 * @return number of unprocessed bytes
+		 */
 		uint8_t buffer_available(void);
+
+		/**
+		 * Get next byte from modem receive buffer.
+		 * @return next unprocessed byte (0 if the buffer is empty)
+		 */
 		uint8_t buffer_get(void);
+
+		/**
+		 * Enable the modem. Turns on the input voltage divider on MODEM_PIN
+		 * and enables the receive interrupt (MODEM_PCINT).
+		 */
 		void enable(void);
+
+		/**
+		 * Disable the modem. Disables the receive interrupt and turns off
+		 * the input voltage divider on MODEM_PIN.
+		 */
 		void disable(void);
+
+		/**
+		 * Called by the pin change interrupt service routine whenever the
+		 * modem pin is toggled. Detects sync pulses, receives bits and
+		 * stores complete bytes in the buffer.
+		 *
+		 * Do not call this function yourself.
+		 */
 		void receive(void);
 };
 
diff --git a/src/system.h b/src/system.h
index 6e2d1b0..b36e348 100644
--- a/src/system.h
+++ b/src/system.h
@@ -16,6 +16,14 @@ class System {
 		void shutdown(void);
 	public:
 		System() { want_shutdown = 0; };
+
+		/**
+		 * System idle loop. Checks for button presses, handles
+		 * standby/resume, reads data from the Modem and updates the Display.
+		 *
+		 * It is recommended to run this function before going back to sleep
+		 * whenever the system is woken up by an interrupt.
+		 */
 		void loop(void);
 };
 
-- 
cgit v1.2.3