Add documentation

space_game/SpaceGame/src/driver/display/display.c

@@ -9,12 +9,12 @@
 
 
 static uint8_t const configuration[] PROGMEM = {
-	0xD5, 0xF0,			// set clock frequency
-	0x8D, 0x14,			// enable charge pump
-	0x20, 0x00,			// horizontal addressing mode
-	0xD6, 0x01,			// 2 times vertical zoom
-	0x22, 0x00, 0x03,	// only draw to the top half of the screen
-	0xAF				// display on
+	0xD5, 0xF0,			/// set clock frequency
+	0x8D, 0x14,			/// enable charge pump
+	0x20, 0x00,			/// horizontal addressing mode
+	0xD6, 0x01,			/// 2 times vertical zoom
+	0x22, 0x00, 0x03,	/// only draw to the top half of the screen
+	0xAF				/// display on
 };
 
 static struct {
@@ -43,8 +43,8 @@ void initializeDisplay(DrawFunction drawEverything) {
 	setOutputPin(DISPLAY_RESET_OUTPUT_PIN, false);
 	for (volatile uint8_t i = 0; i != 255; i++)
 		;
-	// some time has to elapse before the next line gets called,
-	// otherwise the display wont turn on
+	/// some time has to elapse before the next line gets called,
+	/// otherwise the display wont turn on
 	setOutputPin(DISPLAY_RESET_OUTPUT_PIN, true);
 	
 	for (uint8_t i = 0; i < sizeof(configuration); i++) {

space_game/SpaceGame/src/driver/display/display.h

@@ -7,51 +7,51 @@
 #include "../../util/rectangle/rectangle.h"
 
 
-/*
+/**
 	SPI driver for D096-12864
 */
 
 #define DISPLAY_RESET_OUTPUT_PIN PB0
 #define DISPLAY_DC_OUTPUT_PIN PB4
 
-// A two-times downscaling is used for greater performance
+/// A two-times downscaling is used for greater performance
 #define DISPLAY_WIDTH_IN_PIXELS 64
 #define DISPLAY_HEIGHT_IN_PIXELS 32
 
-// To easily access the window size
+/// To easily access the window size
 #define WINDOW ((Rectangle){(Vec2){0, 0}, (Vec2){DISPLAY_WIDTH_IN_PIXELS, DISPLAY_HEIGHT_IN_PIXELS}})
 	
-// To conserve RAM, drawing is done in chunks of DEFAULT_COMPOSITING_WINDOW size
-// instead of buffering the whole display and writing it out at once
+/// To conserve RAM, drawing is done in chunks of DEFAULT_COMPOSITING_WINDOW size
+/// instead of buffering the whole display and writing it out at once
 #define DEFAULT_COMPOSITING_WINDOW ((Rectangle){(Vec2){0, 0}, (Vec2){DISPLAY_WIDTH_IN_PIXELS, 8}})
 
 typedef void (*DrawFunction)(Rectangle);
 
-// Call DrawFunction n times after a call to drawFrame has been made
+/// Call DrawFunction n times after a call to drawFrame has been made
 void initializeDisplay(DrawFunction drawEverything);
 
-// Set a the brightness of the display
-// Value can be any number between 0 and 255.
+/// Set a the brightness of the display
+/// Value can be any number between 0 and 255.
 void setDisplayContrast(uint8_t value);
 
-// To conserve program memory, pixel based intersection test
-// is implemented here.
-// Calling draw functions after calling startIntersectionTest
-// will set a wasIntersection bit appropriately.
+/// To conserve program memory, pixel based intersection test
+/// is implemented here.
+/// Calling draw functions after calling startIntersectionTest
+/// will set a wasIntersection bit appropriately.
 
-// Clear buffer and wasIntersection bit
+/// Clear buffer and wasIntersection bit
 void startIntersectionTest();
 
-// Return wasIntersection bit
+/// Return wasIntersection bit
 bool endIntersectionTest();
 
-// Initiate a draw sequence
+/// Initiate a draw sequence
 void drawFrame();
 
-// Draw a sprite of size boundingBox.size at boundingBox.position from bitmap
-// if isMirrored then mirror around the vertical axis
-// Bitmap's data is interpreted the following way:
-/*
+/// Draw a sprite of size boundingBox.size at boundingBox.position from bitmap
+/// if isMirrored then mirror around the vertical axis
+/// Bitmap's data is interpreted the following way:
+/**
 	Each 16 bit word corresponds to an 8 pixel high column.
 	(These columns are laid out horizontally from left to right. Unfortunately,
 	the display uses this addressing mode.) The higher 8 bits of the word is the 
@@ -63,9 +63,9 @@ void drawFrame();
 */
 void drawBitmapFromProgMem(Rectangle boundingBox, uint16_t const bitmap[boundingBox.size.x][(boundingBox.size.y + 7) / 8], bool isMirrored);
 
-// Draw a one byte repeated texture covering the parameter box
-// for a white rectangle use these arguments: invertedMask: don't care, fill: 0xFF
-// for a black rectangle use these arguments: invertedMask: 0xFF, fill: 0x00
+/// Draw a one byte repeated texture covering the parameter box
+/// for a white rectangle use these arguments: invertedMask: don't care, fill: 0xFF
+/// for a black rectangle use these arguments: invertedMask: 0xFF, fill: 0x00
 void drawFilledRectangle(Rectangle box, uint8_t invertedMask, uint8_t fill);
 
 #endif

space_game/SpaceGame/src/driver/infra/infra.c

@@ -8,11 +8,11 @@
 #include "../uart/receive.h"
 
 
-// (0.5625 + (0.5625 + 1.6875) / 2) / 1000 / timer interval
+/// (0.5625 + (0.5625 + 1.6875) / 2) / 1000 / timer interval
 #define MEAN_OF_0_1_BIT_TIMES 53
-// 9 / 2 / 1000 / timer interval
+/// 9 / 2 / 1000 / timer interval
 #define MAYBE_ONE_CHECK_TIME 141
-// some large value
+/// some large value
 #define TIMEOUT 254
 
 typedef enum {
@@ -139,8 +139,8 @@ ISR(TIM0_COMPB_vect) {
 }
 
 void initializeInfra(OnCommandReceived onCommandReceived) {
-	setBit(PORTB, IR_PIN);	// enable pull-up
-	setBit(PCMSK, IR_PIN);	// specific pin change interrupt enable
-	setBit(GIMSK, PCIE);	// global on pin change interrupt enable;
+	setBit(PORTB, IR_PIN);	/// enable pull-up
+	setBit(PCMSK, IR_PIN);	/// specific pin change interrupt enable
+	setBit(GIMSK, PCIE);	/// global on pin change interrupt enable;
 	infra.onCommandReceived = onCommandReceived;
 }

space_game/SpaceGame/src/driver/infra/infra.h

@@ -5,7 +5,7 @@
 #include <avr/io.h>
 
 
-/*
+/**
 	Custom NEC implementation using a TSOP4838
 */
 
@@ -15,9 +15,9 @@
 
 typedef void (*OnCommandReceived)(uint8_t);
 
-// Initialize infra and call onCommandReceived with every received byte
-// Call onCommandReceived with the argument REPEAT_CODE if a repeat code 
-// has been received.
+/// Initialize infra and call onCommandReceived with every received byte
+/// Call onCommandReceived with the argument REPEAT_CODE if a repeat code 
+/// has been received.
 void initializeInfra(OnCommandReceived onCommandReceived);
 
 #endif

space_game/SpaceGame/src/driver/sleep/sleep.h

@@ -4,10 +4,10 @@
 #include <stdbool.h>
 #include <avr/io.h>
 
-// FrameFunction gets previousFrameTime (in milliseconds) as argument
+/// FrameFunction gets previousFrameTime (in milliseconds) as argument
 typedef bool (*FrameFunction)(uint8_t);
 
-// Call function every frameLengthInMilliseconds while it returns true
+/// Call function every frameLengthInMilliseconds while it returns true
 void startFrameLoop(FrameFunction function, uint8_t frameLengthInMilliseconds);
 
 #endif

space_game/SpaceGame/src/driver/uart/receive.c

@@ -8,7 +8,7 @@
 
 static struct {
 	uint16_t message;
-	uint8_t bitPosition;		// goes from 0 to 9
+	uint8_t bitPosition;		/// goes from 0 to 9
 	bool previousValue;
 	uint8_t previousTimestamp;
 	OnCommandReceived onCommandReceived;
@@ -17,8 +17,8 @@ static struct {
 };
 
 void initializeUartReceive(OnCommandReceived onCommandReceived) {
-	setBit(PORTB, RECEIVE_PIN);		// setup pull-up
-	setBit(PCMSK, RECEIVE_PIN);		// enable interrupt on pin
+	setBit(PORTB, RECEIVE_PIN);		/// setup pull-up
+	setBit(PCMSK, RECEIVE_PIN);		/// enable interrupt on pin
 	uartReceive.onCommandReceived = onCommandReceived;
 }
 

space_game/SpaceGame/src/driver/uart/receive.h

@@ -1,24 +1,24 @@
 #ifndef RECEIVE_H
 #define RECEIVE_H
 
-/* 
+/** 
 	Custom UART receive implementation with a baud rate of 2400
 */
 
 
-// 8*10^6 / 128 / 2400
+/// 8*10^6 / 128 / 2400
 #define BIT_TIME 26
 #define RECEIVE_PIN PB3
 
 typedef void (*OnCommandReceived)(uint8_t);
 
-// Initialize UART and call onCommandReceived with every byte received
+/// Initialize UART and call onCommandReceived with every byte received
 void initializeUartReceive(OnCommandReceived onCommandReceived);
 
-// Check for change on the UART receive pin
-// This function exist so we can use a single interrupt 
-// handler for both the UART receive and infra pins.
-// Unfortunately, it's not possible to use more than one handler.
+/// Check for change on the UART receive pin
+/// This function exist so we can use a single interrupt 
+/// handler for both the UART receive and infra pins.
+/// Unfortunately, it's not possible to use more than one handler.
 void handlePinChangeForUartReceive();
 
 #endif

space_game/SpaceGame/src/driver/uart/transmit.c

@@ -10,7 +10,7 @@ static struct {
 	char bytes[ASYNC_BUFFER_SIZE];
 	uint8_t start;
 	uint8_t end;
-	// 0 - start bit, 1-8 word bits, 9 - end bit 
+	/// 0 - start bit, 1-8 word bits, 9 - end bit 
 	uint8_t currentMaskPosition;
 } uartTransmitter;
 

space_game/SpaceGame/src/driver/uart/transmit.h

@@ -4,30 +4,30 @@
 #include <avr/io.h>
 
 
-/* 
+/** 
 	Custom UART trasnmit implementation with a baud rate of 2400
 */
 
-// 8*10^6 / 128 / 2400
+/// 8*10^6 / 128 / 2400
 #define BIT_TIME 26
 
-// Messages cannot be longer than this many characters (including trailing zero)
+/// Messages cannot be longer than this many characters (including trailing zero)
 #define ASYNC_BUFFER_SIZE 20
 
 #define UART_OUTPUT_PIN 2
 
-// Start pulling-up the transmit line
+/// Start pulling-up the transmit line
 void initializeUartTransmit();
 
-// Send a single byte over on UART
-// It's done in an asynchronous fashion using a circular buffer.
+/// Send a single byte over on UART
+/// It's done in an asynchronous fashion using a circular buffer.
 void sendByteOnUartAsync(char byte);
 
-// Send a string over on UART
-// It's done in an asynchronous fashion using a circular buffer.
+/// Send a string over on UART
+/// It's done in an asynchronous fashion using a circular buffer.
 void sendTextOnUartAsync(char text[]);
 
-// Send the decimal form of unsigned integer over UART
+/// Send the decimal form of unsigned integer over UART
 void sendUintOnUartAsync(uint8_t number);
 
 #endif

space_game/SpaceGame/src/hardware_access/hardware_access.h

@@ -12,40 +12,40 @@
 #include "output_pins/output_pins.h"
 
 
-/*
+/**
 	This module contains the lowest level functions to manipulate the hardware.
 	You only have to include this header file which serves as a facade.
 	The sub-modules' implementation can be freely changed as long as they
 	still implement these functions.
 */
 
-// Initialize every hardware element at once
+/// Initialize every hardware element at once
 void initializeHardwareAccess();
 
-// Enable interrupt OCCRA for TIMER0 with a modulo of triggerInterruptInXTicks
+/// Enable interrupt OCCRA for TIMER0 with a modulo of triggerInterruptInXTicks
 void enableTimerA(uint8_t triggerInterruptInXTicks);
 
-// Enable interrupt OCCRB for TIMER0B with a modulo of triggerInterruptInXTicks
+/// Enable interrupt OCCRB for TIMER0B with a modulo of triggerInterruptInXTicks
 void enableTimerB(uint8_t triggerInterruptInXTicks);
 void disableTimerB();
 
-// Enable interrupt OCCRA for TIMER1 with a modulo of triggerInterruptInXTicks
+/// Enable interrupt OCCRA for TIMER1 with a modulo of triggerInterruptInXTicks
 void enableFastTimerA(uint8_t triggerInterruptInXTicks);
 void disableFastTimerA();
 
-// Return TCNT1
+/// Return TCNT1
 uint8_t getTimestampFromFastTimer();
 
-// Return the time since a timestamp returned by getTimestampFromFastTimer
-// Accounts for overflow.
+/// Return the time since a timestamp returned by getTimestampFromFastTimer
+/// Accounts for overflow.
 uint8_t getTimeSince(uint8_t timestamp);
 
-// Send a single byte on the built-in SPI interface
-// The transfer is done in a serial manner to achieve
-// greater throughput.
+/// Send a single byte on the built-in SPI interface
+/// The transfer is done in a serial manner to achieve
+/// greater throughput.
 void sendByteOnSPI(uint8_t byte);
 
-// Set the value of an output pin
+/// Set the value of an output pin
 void setOutputPin(uint8_t id, bool value);
 
 #endif

space_game/SpaceGame/src/hardware_access/output_pins/output_pins.h

@@ -7,7 +7,7 @@
 
 #define CLK_ST_PIN PB0
 
-// Uses a 74HC595 to extend the number of digital outputs
+/// Uses a 74HC595 to extend the number of digital outputs
 void sendCurrentValue();
 
 inline void initializeOutputPins() {

space_game/SpaceGame/src/hardware_access/power_saving/power_saving.h

@@ -6,8 +6,8 @@
 
 
 inline void initializePowerSaving() {
-	setBit(ACSR, ACD);	// disable ADC to save power
-	PRR = BV(PRADC);	// disable power to ADC (again?)
+	setBit(ACSR, ACD);	/// disable ADC to save power
+	PRR = BV(PRADC);	/// disable power to ADC (again?)
 }
 
 #endif

space_game/SpaceGame/src/hardware_access/spi/spi.h

@@ -9,11 +9,11 @@
 #define USCK_PIN	PB2
 
 inline void initializeSPI() {
-	DDRB |= BV(DO_PIN) | BV(USCK_PIN);	// set pin directions for MOSI and SCK
+	DDRB |= BV(DO_PIN) | BV(USCK_PIN);	/// set pin directions for MOSI and SCK
 }
 
-// This function can be used from other sibling sub-modules
-// it's required for the current outpu_pins implementation.
+/// This function can be used from other sibling sub-modules
+/// it's required for the current outpu_pins implementation.
 void sendByteOnSPI(uint8_t byte);
 
 #endif

space_game/SpaceGame/src/hardware_access/timing/timing.h

@@ -5,9 +5,9 @@
 #include "bitwise.h"
 
 inline void initializeTiming() {
-	TCCR0B = BV(CS02);				 // CLK / 256
-	TCCR1 = BV(CS13);				 // CLK / 128
-	TIMSK = BV(OCIE0A) | BV(OCIE1A); // enable compare interrupts
+	TCCR0B = BV(CS02);				 /// CLK / 256
+	TCCR1 = BV(CS13);				 /// CLK / 128
+	TIMSK = BV(OCIE0A) | BV(OCIE1A); /// enable compare interrupts
 }
 
 #endif

space_game/SpaceGame/src/main.c

@@ -1,12 +1,12 @@
 #include "mediator/mediator.h"
 
 
-// Stemming from the module oriented nature of the project
-// there is a module responsible for setting up and orchestrating
-// the other modules.
-//
-// From the main function we only have to instruct the afromentioned
-// mediator module to do its job.
+/// Stemming from the module oriented nature of the project
+/// there is a module responsible for setting up and orchestrating
+/// the other modules.
+///
+/// From the main function we only have to instruct the aforementioned
+/// mediator module to do its job.
 
 int main(void) {
 	setupConnections();

space_game/SpaceGame/src/mediator/mediator.c

@@ -14,9 +14,9 @@
 #include "../driver/uart/receive.h"
 
 
-#define TARGET_FRAME_DURATION 20	// ms
-#define DEATH_SCREEN_LENGTH 50		// frames
-#define REPORT_INTERVAL 50			// every x frames
+#define TARGET_FRAME_DURATION 20	/// ms
+#define DEATH_SCREEN_LENGTH 50		/// frames
+#define REPORT_INTERVAL 50			/// every x frames
 
 static struct {
 	uint8_t contrast;

space_game/SpaceGame/src/mediator/mediator.h

@@ -4,17 +4,17 @@
 #include <avr/io.h>
 
 
-// Setup the drivers, and business layer objects and their relations
-// It is kind of a very basic dependency injection.
+/// Setup the drivers, and business layer objects and their relations
+/// It is kind of a very basic dependency injection.
 void setupConnections();
 
-// Start drawing frames and ticking objects
+/// Start drawing frames and ticking objects
 void startGame();
 
-// Increase or decrease the contrast (brightness) of the display
-// by the given value
-// The contrast can be any number between 0 and 255.
-// The function automatically clamps the contrast.
+/// Increase or decrease the contrast (brightness) of the display
+/// by the given value
+/// The contrast can be any number between 0 and 255.
+/// The function automatically clamps the contrast.
 void changeDisplayContrast(int8_t by);
 
 #endif

space_game/SpaceGame/src/objects/ai/ai.c

@@ -32,7 +32,7 @@ static AIAction actions[AI_ACTION_COUNT];
 
 
 static Vec2 whichDirectionToMove(Object* astronaut, Vec2 position) {
-	bool const isTargetOnUpperFloor = isOnUpperFloor((Rectangle){position, (Vec2){0, 0}});		// else it's on the lower floor
+	bool const isTargetOnUpperFloor = isOnUpperFloor((Rectangle){position, (Vec2){0, 0}});		/// else it's on the lower floor
 
 	Vec2 const ladder = add(LADDER_BOUNDING_BOX.position, spaceshipObject->position);
 	

space_game/SpaceGame/src/objects/ai/ai.h

@@ -1,12 +1,12 @@
 #ifndef AI_H
 #define AI_H
 
-// Between AI astronauts do actions
-// there has to be at least this many frames
+/// Between AI astronauts do actions
+/// there has to be at least this many frames
 #define AI_ACTION_INTERVAL 15
 
-// If there are non player controlled astronauts
-// control them according to some basic rule set
+/// If there are non player controlled astronauts
+/// control them according to some basic rule set
 void handleAI();
 
 #endif

space_game/SpaceGame/src/objects/commands/commands.h

@@ -1,17 +1,17 @@
 #ifndef COMMANDS_H
 #define COMMANDS_H
 
-// There can be no more than COMMAND_BUFFER_SIZE commands
-// waiting for processing simultaneously
+/// There can be no more than COMMAND_BUFFER_SIZE commands
+/// waiting for processing simultaneously
 #define COMMAND_BUFFER_SIZE 8
 
-// increaseContrast and decreaseContrast changes the contrast
-// with this value
+/// increaseContrast and decreaseContrast changes the contrast
+/// with this value
 #define CONTRAST_STEP 15
 
-// The possible inputs of the system
-// Coincidentally these are the codes of the IR remote
-// controller's buttons.
+/// The possible inputs of the system
+/// Coincidentally these are the codes of the IR remote
+/// controller's buttons.
 typedef enum {
 	noCommand = 0,
 	repeat = 1,
@@ -24,11 +24,11 @@ typedef enum {
 	action = 199,
 } Command;
 
-// Add a new command to the buffer
-// It will not be processed immediately.
+/// Add a new command to the buffer
+/// It will not be processed immediately.
 void addCommand(Command command);
 
-// Process every command in the buffer at once in a FIFO manner
+/// Process every command in the buffer at once in a FIFO manner
 void handleCommands();
 
 #endif