Merge pull request #157 from TomHarte/Documentation

Brings some minor documentation improvements

Components/1770/1770.hpp

@@ -14,20 +14,35 @@
 
 namespace WD {
 
+/*!
+	Provides an emulation of various Western Digital drive controllers, including the
+	WD1770, WD1772, FDC1773 and FDC1793.
+*/
 class WD1770: public Storage::Disk::Controller {
 	public:
 		enum Personality {
-			P1770,	// implies automatic motor-on management with Type 2 commands offering a spin-up disable
+			P1770,	// implies automatic motor-on management, with Type 2 commands offering a spin-up disable
 			P1772,	// as per the 1770, with different stepping rates
 			P1773,	// implements the side number-testing logic of the 1793; omits spin-up/loading logic
 			P1793	// implies Type 2 commands use side number testing logic; spin-up/loading is by HLD and HLT
 		};
+
+		/*!
+			Constructs an instance of the drive controller that behaves according to personality @c p.
+			@param p The type of controller to emulate.
+		*/
 		WD1770(Personality p);
 
+		/// Sets the value of the double-density input; when @c is_double_density is @c true, reads and writes double-density format data.
 		void set_is_double_density(bool is_double_density);
+
+		/// Writes @c value to the register at @c address. Only the low two bits of the address are decoded.
 		void set_register(int address, uint8_t value);
+
+		/// Fetches the value of the register @c address. Only the low two bits of the address are decoded.
 		uint8_t get_register(int address);
 
+		/// Runs the controller for @c number_of_cycles cycles.
 		void run_for_cycles(unsigned int number_of_cycles);
 
 		enum Flag: uint8_t {
@@ -47,8 +62,12 @@ class WD1770: public Storage::Disk::Controller {
 			Busy			= 0x01
 		};
 
+		/// @returns The current value of the IRQ line output.
 		inline bool get_interrupt_request_line()		{	return status_.interrupt_request;	}
+
+		/// @returns The current value of the DRQ line output.
 		inline bool get_data_request_line()				{	return status_.data_request;		}
+
 		class Delegate {
 			public:
 				virtual void wd1770_did_change_output(WD1770 *wd1770) = 0;

Concurrency/AsyncTaskQueue.hpp

@@ -26,7 +26,6 @@ namespace Concurrency {
 	causing it to block until all previously-enqueued functions are complete.
 */
 class AsyncTaskQueue {
-
 	public:
 		AsyncTaskQueue();
 		~AsyncTaskQueue();

Machines/CRTMachine.hpp

@@ -23,12 +23,25 @@ class Machine {
 	public:
 		Machine() : clock_is_unlimited_(false) {}
 
+		/*!
+			Causes the machine to set up its CRT and, if it has one, speaker. The caller guarantees
+			that an OpenGL context is bound.
+		*/
 		virtual void setup_output(float aspect_ratio) = 0;
+
+		/*!
+			Gives the machine a chance to release all owned resources. The caller guarantees that the
+			OpenGL context is bound.
+		*/
 		virtual void close_output() = 0;
 
+		/// @returns The CRT this machine is drawing to. Should not be @c nullptr.
 		virtual std::shared_ptr<Outputs::CRT::CRT> get_crt() = 0;
+
+		/// @returns The speaker that receives this machine's output, or @c nullptr if this machine is mute.
 		virtual std::shared_ptr<Outputs::Speaker> get_speaker() = 0;
 
+		/// Runs the machine for @c number_of_cycle cycles.
 		virtual void run_for_cycles(int number_of_cycles) = 0;
 
 		// TODO: sever the clock-rate stuff.

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;
 };
 

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);
 
 }

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:

NumberTheory/Factors.hpp

@@ -16,6 +16,7 @@ namespace NumberTheory {
 		@returns The greatest common divisor of @c a and @c b as computed by Euclid's algorithm.
 	*/
 	template<class T> T greatest_common_divisor(T a, T b) {
+		// TODO: replace with the C++17 GCD function, once available.
 		if(a < b) {
 			std::swap(a, 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;