From 1bbb4cb478b94bbd16d2b25fc07113281a8ab4ea Mon Sep 17 00:00:00 2001
From: Thomas Harte <thomas.harte@gmail.com>
Date: Sat, 22 Jul 2017 17:39:51 -0400
Subject: [PATCH] Increased documentation.

---
 Machines/KeyboardMachine.hpp  |  8 ++++++++
 Machines/MemoryFuzzer.hpp     |  3 +++
 NumberTheory/CRC.hpp          | 12 ++++++++++++
 StaticAnalyser/Acorn/Disk.hpp |  1 +
 4 files changed, 24 insertions(+)

diff --git a/Machines/KeyboardMachine.hpp b/Machines/KeyboardMachine.hpp
index a5aa972b7..6399d6f58 100644
--- a/Machines/KeyboardMachine.hpp
+++ b/Machines/KeyboardMachine.hpp
@@ -13,7 +13,15 @@ namespace KeyboardMachine {
 
 class Machine {
 	public:
+		/*!
+			Indicates that the key @c key has been either pressed or released, according to
+			the state of @c isPressed.
+		*/
 		virtual void set_key_state(uint16_t key, bool isPressed) = 0;
+
+		/*!
+			Instructs that all keys should now be treated as released.
+		*/
 		virtual void clear_all_keys() = 0;
 };
 
diff --git a/Machines/MemoryFuzzer.hpp b/Machines/MemoryFuzzer.hpp
index 3de6bdcbd..614692d54 100644
--- a/Machines/MemoryFuzzer.hpp
+++ b/Machines/MemoryFuzzer.hpp
@@ -15,7 +15,10 @@
 
 namespace Memory {
 
+/// Stores @c size random bytes from @c buffer onwards.
 void Fuzz(uint8_t *buffer, size_t size);
+
+// Replaces all existing vector contents with random bytes.
 void Fuzz(std::vector<uint8_t> &buffer);
 
 }
diff --git a/NumberTheory/CRC.hpp b/NumberTheory/CRC.hpp
index b9f4aed3e..801495b81 100644
--- a/NumberTheory/CRC.hpp
+++ b/NumberTheory/CRC.hpp
@@ -13,8 +13,13 @@
 
 namespace NumberTheory {
 
+/*! Provides a class capable of accumulating a CRC16 from source data. */
 class CRC16 {
 	public:
+		/*!
+			Instantiates a CRC16 that will compute the CRC16 specified by the supplied
+			@c polynomial and @c reset_value.
+		*/
 		CRC16(uint16_t polynomial, uint16_t reset_value) :
 				reset_value_(reset_value), value_(reset_value) {
 			for(int c = 0; c < 256; c++) {
@@ -27,11 +32,18 @@ class CRC16 {
 			}
 		}
 
+		/// Resets the CRC to the reset value.
 		inline void reset() { value_ = reset_value_; }
+
+		/// Updates the CRC to include @c byte.
 		inline void add(uint8_t byte) {
 			value_ = (uint16_t)((value_ << 8) ^ xor_table[(value_ >> 8) ^ byte]);
 		}
+
+		/// @returns The current value of the CRC.
 		inline uint16_t get_value() const {	return value_; }
+
+		/// Sets the current value of the CRC.
 		inline void set_value(uint16_t value) { value_ = value; }
 
 	private:
diff --git a/StaticAnalyser/Acorn/Disk.hpp b/StaticAnalyser/Acorn/Disk.hpp
index 5b7bc3ed7..43e6810c0 100644
--- a/StaticAnalyser/Acorn/Disk.hpp
+++ b/StaticAnalyser/Acorn/Disk.hpp
@@ -15,6 +15,7 @@
 namespace StaticAnalyser {
 namespace Acorn {
 
+/// Describes a DFS- or ADFS-format catalogue(/directory) — the list of files available and the catalogue's boot option.
 struct Catalogue {
 	std::string name;
 	std::list<File> files;