From 541b0f27054f27e661a71aa465e2df6e5a1c0b86 Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@finalrewind.org>
Date: Sun, 14 Feb 2016 19:04:17 +0100
Subject: update modem/fecmodem documentation

---
 src/fecmodem.h | 20 ++++++++++++++++++++
 src/modem.h    |  8 +++++++-
 2 files changed, 27 insertions(+), 1 deletion(-)

(limited to 'src')

diff --git a/src/fecmodem.h b/src/fecmodem.h
index 00487ee..c9a942b 100644
--- a/src/fecmodem.h
+++ b/src/fecmodem.h
@@ -7,6 +7,12 @@
 #include "hamming.h"
 #include "modem.h"
 
+/**
+ * Receive-only modem with forward error correction.
+ * Uses the Modem class to read raw modem data and uses the Hamming 2416
+ * algorithm to detect and, if possible, correct transmission errors.
+ * Exposes a global modem object for convenience.
+ */
 class FECModem : public Modem {
 	private:
 		enum HammingState : uint8_t {
@@ -22,7 +28,21 @@ class FECModem : public Modem {
 		uint8_t hamming2416(uint8_t *byte1, uint8_t *byte2, uint8_t parity);
 	public:
 		FECModem() : Modem() { hammingState = FIRST_BYTE; };
+
+		/**
+		 * Checks if there are unprocessed bytes in the receive buffer.
+		 * Parity bytes are accounted for, so if three raw bytes (two data,
+		 * one parity) were received by Modem::receive(), this function will
+		 * return 2.
+		 * @return number of unprocessed data bytes
+		 */
 		uint8_t buffer_available(void);
+
+		/**
+		 * Get next byte from the receive buffer.
+		 * @return received byte (0 if it contained uncorrectable errors
+		 *         or the buffer is empty)
+		 */
 		uint8_t buffer_get(void);
 };
 
diff --git a/src/modem.h b/src/modem.h
index 6b40ac6..a2156a3 100644
--- a/src/modem.h
+++ b/src/modem.h
@@ -25,7 +25,7 @@
 /**
  * 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.
+ * transmission errors.
  */
 class Modem {
 	private:
@@ -37,6 +37,12 @@ class Modem {
 	public:
 		Modem() {new_transmission = false;};
 
+		/**
+		 * Checks if a new transmission was started since the last call
+		 * to this function. Returns true if that is the case and false
+		 * otherwise.
+		 * @return true if a new transmission was started
+		 */
 		bool newTransmission();
 
 		/**
-- 
cgit v1.2.3