added Doxygen configuration file, revised in-place documentation

animations/bitmapscroller.c

@@ -1,3 +1,14 @@
+/**
+ * \defgroup bitmap Bitmap scroller for the Borg.
+ * @{
+ */
+
+/**
+ * @file bitmapscroller.c
+ * @brief Implementation of a bitmap scroller for the Borg.
+ * @author Christian Kroll
+ */
+
 #include <stdlib.h>
 #include <stdint.h>
 #include <assert.h>
@@ -25,7 +36,7 @@ typedef struct bitmap_t
 	unsigned char nXDomain;        /**< Last valid x-coordinate for viewport. */
 	unsigned char nYDomain;        /**< Last valid y-coordinate for viewport. */
 	unsigned char nChunkDomain;    /**< Last valid chunk for viewport. */
-	unsigned char nChunkCount;     /**< Amount of horiz. chunks of the bitmap.*/
+	unsigned char nChunkCount;     /**< Number of horiz. chunks of the bitmap.*/
 }
 bitmap_t;
 
@@ -175,11 +186,11 @@ static void bitmap_recalculateVector(bitmap_t const *const pBitmap,
  * This function scrolls through a bitmap.
  * @param nWidth Width of the bitmap.
  * @param nHeight Height of bitmap.
- * @param nBitPlanes Amount of bit planes.
+ * @param nBitPlanes Number of bit planes.
  * @param nTickCount How many ticks the animation will last.
  * @param nTick Time quantum in milliseconds.
- * @param nFrameTickDivider Amount of ticks between frame changes.
+ * @param nFrameTickDivider Number of ticks between frame changes.
- * @param nMovementTickDiver Amount of ticks between movement changes.
+ * @param nMovementTickDiver Number of ticks between movement changes.
  * @param fpGetChunk Function that returns an eight-by-one chunk of a bitmap.
  */
 void bitmap_scroll(unsigned char const nWidth,
@@ -234,3 +245,5 @@ void bitmap_scroll(unsigned char const nWidth,
 		wait(nTick);
 	}
 }
+
+/*@}*/

animations/bitmapscroller.h

@@ -1,3 +1,14 @@
+/**
+ * \addtogroup bitmap
+ * @{
+ */
+
+/**
+ * @file bitmapscroller.h
+ * @brief Public interface for the Borg's bitmap scroller.
+ * @author Christian Kroll
+ */
+
 #ifndef BITMAP_SCROLLER_H_
 #define BITMAP_SCROLLER_H_
 
@@ -33,3 +44,5 @@ void bitmap_scroll(unsigned char const nWidth,
                    bitmap_getChunk_t fpGetChunk);
 
 #endif /* BITMAP_SCROLLER_H_ */
+
+/*@}*/

animations/fpmath_patterns.c

@@ -1,5 +1,12 @@
 /**
- * Routines for drawing patterns generated by fixed point math functions.
+ * \defgroup fixedpoint Fixed-point based animated plasma patterns.
+ */
+/*@{*/
+
+/**
+ * @file fpmath_patterns.c
+ * @brief Routines for drawing patterns generated by fixed-point math functions.
+ * @author Christian Kroll
  */
 
 #include <assert.h>
@@ -10,10 +17,6 @@
 #include "../util.h"
 #include "fpmath_patterns.h"
 
-/**
- * \defgroup fixedpoint Fixed-point based animated plasma patterns.
- */
-/*@{*/
 
 /**
  * Double buffering helps in reducing the effect of visibly redrawing every
@@ -52,26 +55,26 @@
 #ifdef LOW_PRECISION
 	/** This is the type we expect ordinary integers to be. */
 	typedef int16_t  ordinary_int_t;
-	/** This is the type which we use for fixed point values. */
+	/** This is the type which we use for fixed-point values. */
 	typedef int16_t  fixp_t;
 	/** This type covers arguments of fixSin() and fixCos(). */
 	typedef int16_t  fixp_trig_t;
-	/** This type covers interim results of fixed point operations. */
+	/** This type covers interim results of fixed-point operations. */
 	typedef uint32_t  fixp_interim_t;
-	/** This type covers interim results of the fixed point sqrt() function. */
+	/** This type covers interim results of the fixSqrt() function. */
 	typedef uint16_t ufixp_interim_t;
-	/** Amount of bits the fixed point sqrt() function can handle. */
+	/** Number of bits the fixSqrt() function can handle. */
 	#define SQRT_BITS 16
 
 	// NOTE: If you change the following values, don't forget to adapt the sine
 	// lookup table as well!
 
-	/** Multiply a number by this factor to convert it to a fixed point value.*/
+	/** Multiply a number by this factor to convert it to a fixed-point value.*/
 	#define FIX           32
-	/**	Amount of fractional bits of a value (i.e. ceil(log_2(FIX))). */
+	/**	Number of fractional bits of a value (i.e. ceil(log_2(FIX))). */
 	#define FIX_FRACBITS  5
 	/**
-	 * The amount of temporal quantization steps of the sine lookup table. It
+	 * The number of temporal quantization steps of the sine lookup table. It
 	 * must be a divisor of (FIX * 2 * pi) and this divisor must be divisable by
 	 * 4 itself. Approximate this value as close as possible to keep rounding
 	 * errors at a minimum.
@@ -99,26 +102,26 @@
 #else
 	/** This is the type we expect ordinary integers to be. */
 	typedef int16_t  ordinary_int_t;
-	/** This is the type which we use for fixed point values. */
+	/** This is the type which we use for fixed-point values. */
 	typedef int16_t  fixp_t;
 	/** This type covers arguments of fixSin() and fixCos(). */
 	typedef int32_t  fixp_trig_t;
-	/** This type covers interim results of fixed point operations. */
+	/** This type covers interim results of fixed-point operations. */
 	typedef int32_t  fixp_interim_t;
-	/** This type covers interim results of the fixed point sqrt() function. */
+	/** This type covers interim results of the fixSqrt() function. */
 	typedef uint32_t ufixp_interim_t;
-	/** Amount of bits the fixed point sqrt() function can handle. */
+	/** Number of bits the fixSqrt() function can handle. */
 	#define SQRT_BITS 32
 
 	// NOTE: If you change the following values, don't forget to adapt the sine
 	// lookup table as well!
 
-	/** Multiply a number by this factor to convert it to a fixed point value.*/
+	/** Multiply a number by this factor to convert it to a fixed-point value.*/
 	#define FIX           256
-	/**	Amount of fractional bits of a value (i.e. ceil(log_2(FIX))). */
+	/**	Number of fractional bits of a value (i.e. ceil(log_2(FIX))). */
 	#define FIX_FRACBITS  8
 	/**
-	 * The amount of temporal quantization steps of the sine lookup table. It
+	 * The number of temporal quantization steps of the sine lookup table. It
 	 * must be a divisor of (FIX * 2 * pi) and this divisor must be divisable by
 	 * 4 itself. Approximate this value as close as possible to keep rounding
 	 * errors at a minimum.
@@ -149,18 +152,18 @@
 
 /** The ordinary pi constant. */
 #define PI                  3.14159265358979323846
-/** Fixed point version of (pi / 2). */
+/** Fixed-point version of (pi / 2). */
 #define FIX_PI_2            ((fixp_t)(PI * FIX / 2))
-/** Fixed point version of pi. */
+/** Fixed-point version of pi. */
 #define FIX_PI              ((fixp_t)(PI * FIX))
-/** Fixed point version of (2 * pi). */
+/** Fixed-point version of (2 * pi). */
 #define FIX_2PI             ((fixp_t)(2 * PI * FIX))
 
 
 /**
- * Scales an ordinary integer up to its fixed point format.
+ * Scales an ordinary integer up to its fixed-point format.
- * @param a an ordinary integer to be scaled up
+ * @param a An ordinary integer to be scaled up.
- * @return The given value in fixed point format.
+ * @return The given value in fixed-point format.
  */
 inline static fixp_t fixScaleUp(ordinary_int_t a)
 {
@@ -169,10 +172,10 @@ inline static fixp_t fixScaleUp(ordinary_int_t a)
 
 
 /**
- * Scales a fixed point value down to an ordinary integer (omitting the
+ * Scales a fixed-point value down to an ordinary integer (omitting the
  * fractional part).
- * @param a fixed point value to be scaled down
+ * @param a Fixed-point value to be scaled down to an integer.
- * @return The given value in fixed point format.
+ * @return The given value as an integer.
  */
 inline static ordinary_int_t fixScaleDown(fixp_t const a)
 {
@@ -181,9 +184,9 @@ inline static ordinary_int_t fixScaleDown(fixp_t const a)
 
 
 /**
- * Multiplies two fixed point values.
+ * Multiplies two fixed-point values.
- * @param a operand a
+ * @param a A multiplicand.
- * @param b operand b
+ * @param b A multiplying factor.
  * @return Product of a and b.
  */
 inline static fixp_interim_t fixMul(fixp_t const a, fixp_t const b)
@@ -193,9 +196,9 @@ inline static fixp_interim_t fixMul(fixp_t const a, fixp_t const b)
 
 
 /**
- * Divides two fixed point values.
+ * Divides two fixed-point values.
- * @param a operand a
+ * @param a A dividend.
- * @param b operand b
+ * @param b A divisor.
  * @return Quotient of a and b.
  */
 inline static fixp_t fixDiv(fixp_interim_t const a, fixp_interim_t const b)
@@ -205,13 +208,13 @@ inline static fixp_t fixDiv(fixp_interim_t const a, fixp_interim_t const b)
 
 
 /**
- * Fixed point variant of the sine function which receives a fixed point angle
+ * Fixed-point variant of the sine function which receives a fixed-point angle
  * (radian). It uses a lookup table which models the first quarter of a full
  * sine period and calculates the rest from that quarter.
- * @param angle fixed point radian value
+ * @param fAngle A fixed-point value in radian.
  * @return Result of the sine function normalized to a range from -FIX to FIX.
  */
-static fixp_t fixSin(fixp_t fAngle)
+static fixp_t fixSin(fixp_trig_t fAngle)
 {
 	// convert given fixed-point angle to its corresponding quantization step
 	int8_t nSign = 1;
@@ -251,22 +254,22 @@ static fixp_t fixSin(fixp_t fAngle)
 
 
 /**
- * Fixed point variant of the cosine function which takes a fixed point angle
+ * Fixed-point variant of the cosine function which takes a fixed-point angle
  * (radian). It adds FIX_PI_2 to the given angle and consults the fixSin()
  * function for the final result.
- * @param angle fixed point radian value
+ * @param fAngle A fixed-point value in radian.
  * @return Result of the cosine function normalized to a range from -FIX to FIX.
  */
-static fixp_t fixCos(fixp_t const angle)
+static fixp_t fixCos(fixp_trig_t const fAngle)
 {
-	return fixSin(angle + FIX_PI_2);
+	return fixSin(fAngle + FIX_PI_2);
 }
 
 
 /**
- * Fixed point square root algorithm as proposed by Ken Turkowski:
+ * Fixed-point square root algorithm as proposed by Ken Turkowski:
  * http://www.realitypixels.com/turk/computergraphics/FixedSqrt.pdf
- * @param radicant we want the square root of
+ * @param a The radicant we want the square root of.
  * @return The square root of the given value.
  */
 static fixp_t fixSqrt(ufixp_interim_t const a)
@@ -295,11 +298,11 @@ static fixp_t fixSqrt(ufixp_interim_t const a)
 
 /**
  * Calculates the distance between two points.
- * @param x1 x coordinate of the first point
+ * @param x1 x-coordinate of the first point
- * @param y1 y coordinate of the first point
+ * @param y1 y-coordinate of the first point
- * @param x2 x coordinate of the second point
+ * @param x2 x-coordinate of the second point
- * @param y2 y coordinate of the second point
+ * @param y2 y-coordinate of the second point
- * @return The distance between the given coordinates.
+ * @return The distance between the given points.
  */
 static fixp_t fixDist(fixp_t const x1,
                       fixp_t const y1,
@@ -312,12 +315,12 @@ static fixp_t fixDist(fixp_t const x1,
 
 /**
  * This pointer type covers functions which return a brightness value for the
- * given coordinates and a "step" value. This actually results in a more or less
+ * given coordinates and a "step" value. Applied to all coordinates of the
- * "beautiful" pattern.
+ * borg's display this actually results in a more or less beautiful pattern.
  * @param x x-coordinate
  * @param y y-coordinate
- * @param t step value which changes for each frame, allowing for animations
+ * @param t A step value which changes for each frame, allowing for animations.
- * @param r pointer to persistent data required by the pattern function
+ * @param r A pointer to persistent data required by the pattern function.
  * @return The brightness value (0 < n <= NUM_PLANES) of the given coordinate.
  */
 typedef unsigned char (*fpmath_pattern_func_t)(unsigned char const x,
@@ -334,12 +337,12 @@ typedef unsigned char (*fpmath_pattern_func_t)(unsigned char const x,
 
 /**
  * Draws an animated two dimensional graph for a given function f(x, y, t).
- * @param t_start start value for the function's step variable
+ * @param t_start  A start value for the function's step variable.
- * @param t_stop stop value for the function's step variable
+ * @param t_stop A stop value for the function's step variable.
- * @param t_delta value by which the function's step variable gets incremented
+ * @param t_delta Value by which the function's step variable gets incremented.
- * @param frame_delay frame delay in milliseconds
+ * @param frame_delay The frame delay in milliseconds.
- * @param fpPattern function which generates a pattern depending on x, y and t
+ * @param fpPattern Function which generates a pattern depending on x, y and t.
- * @param r pointer to persistent data required by the fpPattern function
+ * @param r A pointer to persistent data required by the fpPattern function.
  */
 static void fixPattern(fixp_t const t_start,
                        fixp_t const t_stop,
@@ -387,22 +390,42 @@ static void fixPattern(fixp_t const t_start,
 /**
  * This type maintains values relevant for the Plasma animation which need to be
  * persistent over consecutive invocations.
+ * @see fixAnimPlasma()
  */
 typedef struct fixp_plasma_s
 {
-	fixp_t fFunc1[NUM_COLS]; /**< Result of 1st trig. func. depending on x. */
+	/**
-	fixp_t fFunc2CosArg; /**< Arg. of 2st trig. func. depending on the frame. */
+	 * This array holds column dependent results of the first internal pattern
-	fixp_t fFunc2SinArg; /**< Arg. of 2st trig. func. depending on the frame. */
+	 * function. Those results only need to be calculated for the first row of
+	 * the current frame and are then reused for the remaining rows.
+	 */
+	fixp_t fFunc1[NUM_COLS];
+	/**
+	 * This value is part of the formula for the second internal pattern
+	 * function. It needs to be calculated only once per frame.
+	 */
+	fixp_t fFunc2CosArg;
+	/**
+	 * This value is part of the formula for the second internal pattern
+	 * function. It needs to be calculated only once per frame.
+	 */
+	fixp_t fFunc2SinArg;
 } fixp_plasma_t;
 
 
 /**
  * Draws a plasma like pattern (sort of... four shades of grey are pretty
- * scarce for a neat plasma animation).
+ * scarce for a neat plasma animation). This is realized by superimposing two
+ * functions which generate independent patterns for themselves.
+ *
+ * The first function draws horizontally moving waves and the second function
+ * draws zoomed-in radiating curls. Together they create a wobbly, plasma like
+ * pattern.
+ *
  * @param x x-coordinate
  * @param y y-coordinate
- * @param t step value which changes for each frame, allowing for animations
+ * @param t A Step value which changes for each frame, allowing for animations.
- * @param r pointer to persistent interim results
+ * @param r A pointer to persistent interim results.
  * @return The brightness value (0 < n <= NUM_PLANES) of the given coordinate.
  */
 static unsigned char fixAnimPlasma(unsigned char const x,
@@ -439,7 +462,9 @@ static unsigned char fixAnimPlasma(unsigned char const x,
 	return nRes;
 }
 
-
+/**
+ * Starting point for the Plasma animation.
+ */
 void plasma(void)
 {
 	fixp_plasma_t r;
@@ -461,9 +486,9 @@ void plasma(void)
  */
 typedef struct fixp_psychedelic_s
 {
-	fixp_t fCos;         /** column factor for the circle calculation */
+	fixp_t fCos;         /**< One of the column factors of the curl. */
-	fixp_t fSin;         /** row factor for the circle calculation */
+	fixp_t fSin;         /**< One of the row factors of the curl. */
-	fixp_interim_t ft10; /** value involved in rotating the animation's center*/
+	fixp_interim_t ft10; /**< A value involved in rotating the curl's center. */
 } fixp_psychedelic_t;
 
 
@@ -471,8 +496,8 @@ typedef struct fixp_psychedelic_s
  * Draws flowing circular waves with a rotating center.
  * @param x x-coordinate
  * @param y y-coordinate
- * @param t step value which changes for each frame, allowing for animations
+ * @param t A step value which changes for each frame, allowing for animations.
- * @param r pointer to persistent interim results
+ * @param r A pointer to persistent interim results.
  * @return The brightness value (0 < n <= NUM_PLANES) of the given coordinate.
  */
 static unsigned char fixAnimPsychedelic(unsigned char const x,
@@ -500,6 +525,10 @@ static unsigned char fixAnimPsychedelic(unsigned char const x,
 	return nResult;
 }
 
+
+/**
+ * Starting point for the Psychedelic animation.
+ */
 void psychedelic(void)
 {
 	fixp_psychedelic_t r;

animations/fpmath_patterns.h

@@ -1,3 +1,14 @@
+/**
+ * \addtogroup fixedpoint
+ * @{
+ */
+
+/**
+ * @file fpmath_patterns.h
+ * @brief Public starting points for the fixed-point math based animations.
+ * @author Christian Kroll
+ */
+
 #ifndef FPMATH_PATTERNS_H_
 #define FPMATH_PATTERNS_H_
 
@@ -6,3 +17,5 @@ void plasma(void);
 void psychedelic(void);
 
 #endif /* FPMATH_PATTERNS_H_ */
+
+/*@}*/

animations/mherweg.c

@@ -1,3 +1,21 @@
+/**
+ * \defgroup mherweg Martin Herweg's animations.
+ * @{
+ */
+
+/**
+ * @file mherweg.c
+ * @brief Simple animations for getting started with developing for the Borg.
+ * @details The following animations were developed by Martin Herweg (hence the
+ *          name) as a personal aid for getting familiar with developing for the
+ *          Borg.
+ *
+ *          Although these animations are rarely used among Borg owners, we left
+ *          them in because of their simplicity in hopes that a novice Borg
+ *          developer may find them useful.
+ * @author Martin Herweg
+ */
+
 #include "../compat/pgmspace.h"
 #include "../random/prng.h"
 #include "../config.h"
@@ -5,24 +23,15 @@
 #include "../util.h"
 
 
-/*
+/** macro for simplifying flash memory access */
- * The following animations were developed by Martin Herweg (hence the name)
- * as a personal aid for getting familiar with programming the Borg.
- *
- * Although these animations are rarely used among Borg owners, we left them in
- * because of their simplicity in hopes that a novice Borg developer may find
- * them useful.
- */
-
-
-// macro for simplifying flash memory access
 #define PGM(x) pgm_read_byte(&(x))
 
 
-// use 8 bit operands where feasible
 #if NUM_ROWS < 64 && NUM_COLS < 64
+	/** use 8 bit operands where feasible */
 	typedef signed char operand_t;
 #else
+	/** use 16 bit operands if either width or height are >= 64 */
 	typedef int operand_t;
 #endif
 
@@ -283,3 +292,5 @@ void mherweg()
 	rectangle1();
 	rectangles();
 }
+
+/*@}*/

animations/mherweg.h

@@ -1,6 +1,19 @@
+/**
+ * \addtogroup mherweg
+ * @{
+ */
+
+/**
+ * @file mherweg.h
+ * @brief Public starting point for Martin Herweg's animations.
+ * @author Martin Herweg
+ */
+
 #ifndef MHERWEG_H_
 #define MHERWEG_H_
 
 void mherweg();
 
 #endif /* MHERWEG_H_ */
+
+/*@}*/

animations/snake.c

@@ -1,3 +1,16 @@
+/**
+ * \addtogroup Snake
+ *
+ * @{
+ */
+
+/**
+ * @file snake.c
+ * @brief Starting point for the snake engine in demo mode.
+ * @author Peter Fuhrmann, Martin Ongsiek, Daniel Otte, Christian Kroll
+ */
+
+
 #include "../games/snake/snake_game.h"
 
 /**
@@ -7,3 +20,5 @@ void snake_animation(void)
 {
 	snake_engine(1);
 }
+
+/*@}*/

animations/snake.h

@@ -1,6 +1,20 @@
+/**
+ * \addtogroup Snake
+ *
+ * @{
+ */
+
+/**
+ * @file snake.h
+ * @brief Public starting point for the snake engine in demo mode.
+ * @author Peter Fuhrmann, Martin Ongsiek, Daniel Otte, Christian Kroll
+ */
+
 #ifndef SNAKE_H_
 #define SNAKE_H_
 
 void snake_animation(void);
 
 #endif /* SNAKE_H_ */
+
+/*@}*/

borg_hw/borg_hw.h

@@ -1,7 +1,7 @@
 #ifndef BORG_HW_H
 #define BORG_HW_H
 
-// LINEBYTES holds the amount of bytes per line within the framebuffer (pixmap)
+// LINEBYTES holds the number of bytes per line within the frame buffer (pixmap)
 #define LINEBYTES (((NUM_COLS-1)/8)+1)
 
 

games/snake/snake_game.c

@@ -1,3 +1,15 @@
+/**
+ * \defgroup Snake Snake, a casual game including a demo mode.
+ *
+ * @{
+ */
+
+/**
+ * @file snake_game.c
+ * @brief Implementation of the snake game.
+ * @author Peter Fuhrmann, Martin Ongsiek, Daniel Otte, Christian Kroll
+ */
+
 #include <assert.h>
 #include <stdint.h>
 #include "../../config.h"
@@ -9,6 +21,7 @@
 #include "../../menu/menu.h"
 #include "snake_game.h"
 
+
 #if defined MENU_SUPPORT && defined GAME_SNAKE
 // snake icon (MSB is leftmost pixel)
 static const uint8_t icon[8] PROGMEM =
@@ -22,55 +35,62 @@ game_descriptor_t snake_game_descriptor __attribute__((section(".game_descriptor
 #endif
 
 
-// If defined, joystick controls are NOT as "seen" by the snake but absolute,
+/**
-// that is, if pressing up, snake goes up, etc.
+ * If defined, joystick controls are NOT as "seen" by the snake but absolute,
+ * that is, if pressing up, snake goes up, etc.
+ */
 #define SNAKE_NEWCONTROL
 
-// limits
+#if !defined USNAKE_MAX_LENGTH || defined DOXYGEN
-#ifndef USNAKE_MAX_LENGTH
+	/** The maximum length of the snake. */
 	#define USNAKE_MAX_LENGTH 64u
 #endif
 
-#ifndef SNAKE_MAX_APPLES
+#if !defined SNAKE_MAX_APPLES || defined DOXYGEN
+	/** The maximum number of apples lying on the playing field. */
 	#define SNAKE_MAX_APPLES 10
 #endif
 
-// delays (in milliseconds)
+#if !defined SNAKE_CYCLE_DELAY || defined DOXYGEN
-#ifndef SNAKE_CYCLE_DELAY
+	/** Delay (in ms) between every state change. */
 	#define SNAKE_CYCLE_DELAY 100
 #endif
-#ifndef SNAKE_TERMINATION_DELAY
+
+#if !defined SNAKE_TERMINATION_DELAY || defined DOXYGEN
+	/** Delay (in ms) between every disappearing pixel of a dying snake. */
 	#define SNAKE_TERMINATION_DELAY 60
 #endif
 
-// colors
+/** The color of the surrounding border. */
 #define SNAKE_COLOR_BORDER 3
+/** The color of the snake. */
 #define SNAKE_COLOR_PROTAGONIST 3
+/** The color of the apples. */
 #define SNAKE_COLOR_APPLE 3
 
 
 /**
  * Directions of the snake.
  */
-enum snake_dir
+enum snake_dir_e
 {
-	SNAKE_DIR_UP,   //!< SNAKE_DIR_UP    Snake is heading up.
+	SNAKE_DIR_UP,   /**< Snake is heading up. */
-	SNAKE_DIR_RIGHT,//!< SNAKE_DIR_RIGHT Snake is heading right.
+	SNAKE_DIR_RIGHT,/**< Snake is heading right. */
-	SNAKE_DIR_DOWN, //!< SNAKE_DIR_DOWN  Snake is heading down.
+	SNAKE_DIR_DOWN, /**< Snake is heading down. */
-	SNAKE_DIR_LEFT, //!< SNAKE_DIR_LEFT  Snake is heading left.
+	SNAKE_DIR_LEFT, /**< Snake is heading left. */
-	SNAKE_DIR_NONE  //!< SNAKE_DIR_NONE  Helper value for a "resting" joystick.
+	SNAKE_DIR_NONE  /**< Helper value for a "resting" joystick. */
 };
 #ifdef NDEBUG
 	typedef uint8_t snake_dir_t;
 #else
-	typedef enum snake_dir snake_dir_t;
+	typedef enum snake_dir_e snake_dir_t;
 #endif
 
 /**
  * This structure represents the snake character itself. It keeps track of the
  * snake's segments, its head and tail and the direction it is heading.
  */
-typedef struct snake_protagonist
+typedef struct snake_protagonist_s
 {
 	pixel aSegments[USNAKE_MAX_LENGTH]; /**< All segments of the snake. */
 	uint8_t nHeadIndex;                 /**< Index of the head segment. */
@@ -82,20 +102,22 @@ typedef struct snake_protagonist
 /**
  * This structure keeps track of all apples which are on the playing field.
  */
-typedef struct snake_apples
+typedef struct snake_apples_s
 {
-	pixel aApples[SNAKE_MAX_APPLES]; /**< All apple positions */
+	pixel aApples[SNAKE_MAX_APPLES]; /**< Positions of all existing apples. */
-	uint8_t nAppleCount;             /**< Counter of currently existing apples*/
+	uint8_t nAppleCount;             /**< Count of currently existing apples. */
 } snake_apples_t;
 
 
 /**
- * Moves a pixel to the given direction.
+ * This function returns the next position which is calculated from a given
- * @param pxNext pixel to be moved
+ * (current) position and a direction.
- * @param dir direction
+ * @param pxNext The position we're going to leave.
+ * @param dir The direction that we are heading.
+ * @return The next position according the given direction.
  */
-static pixel snake_applyDirection(pixel pxNext,
+static pixel snake_nextDirection(pixel const pxNext,
-                                  snake_dir_t dir)
+                                 snake_dir_t const dir)
 {
 	assert(dir < 4);
 	static int8_t const nDelta[] = {0, -1, 0, 1, 0};
@@ -104,7 +126,7 @@ static pixel snake_applyDirection(pixel pxNext,
 
 
 /**
- * This functions draws a border around the playing field.
+ * This function draws a border around the playing field.
  */
 static void snake_drawBorder(void)
 {
@@ -132,8 +154,9 @@ static void snake_drawBorder(void)
 
 #ifdef GAME_SNAKE
 /**
- * Translates port information into directions.
+ * This function translates hardware port information into joystick directions.
- * @return Current direction of the joystick
+ * @return The current direction of the joystick.
+ * @see snake_dir_e
  */
 static snake_dir_t snake_queryJoystick(void)
 {
@@ -164,8 +187,8 @@ static snake_dir_t snake_queryJoystick(void)
 #endif
 
 /**
- * Initializes the structure which represents the snake itself.
+ * This function initializes the structure which represents the snake itself.
- * @param pprotSnake The protagonist structure to be initialized.
+ * @param pprotSnake The pointer the protagonist structure to be initialized.
  */
 static void snake_initGameProtagonist(snake_protagonist_t *pprotSnake)
 {
@@ -176,12 +199,11 @@ static void snake_initGameProtagonist(snake_protagonist_t *pprotSnake)
 	pprotSnake->dir = SNAKE_DIR_UP;
 }
 
-
 #ifdef GAME_SNAKE
 /**
- * Determines the next direction of the snake depending on joystick input.
+ * Determines the next direction of the snake depending on the joystick's input.
- * @param pprotSnake Protagonist structure to be controlled.
+ * @param pprotSnake A pointer to the structure of the protagonist.
- * @param pdirLast The last joystick movement to avoid key repeat.
+ * @param pdirLast Last joystick direction to recognize prolonged key presses.
  */
 static void snake_userControl(snake_protagonist_t *pprotSnake,
                               snake_dir_t *pdirLast)
@@ -198,7 +220,8 @@ static void snake_userControl(snake_protagonist_t *pprotSnake,
 	}
 #else
 	if ((dirJoystick ^ *pdirLast) && (dirJoystick != SNAKE_DIR_NONE))
-	{		// only left or right movements are valid
+	{
+		// only left or right movements are valid
 		if (dirJoystick & 0x01)
 		{
 			// rotate through directions (either clockwise or counterclockwise)
@@ -214,9 +237,10 @@ static void snake_userControl(snake_protagonist_t *pprotSnake,
 
 #ifdef ANIMATION_SNAKE
 /**
- * Approaches directions which may lead to an apple.
+ * This function approximates the next direction which may lead to an apple
- * @param pprotSnake The hungry protagonist.
+ * (with a particular probability).
- * @param pApples A bunch of apples.
+ * @param pprotSnake A pointer to the hungry protagonist.
+ * @param pApples A pointer to a bunch of apples.
  */
 static void snake_autoRoute(snake_protagonist_t *pprotSnake,
                             snake_apples_t *pApples)
@@ -271,7 +295,7 @@ static void snake_autoRoute(snake_protagonist_t *pprotSnake,
 
 	for (uint8_t i = 0; i < 4; ++i)
 	{
-		pixel pxTest = snake_applyDirection(pxHead, pprotSnake->dir);
+		pixel pxTest = snake_nextDirection(pxHead, pprotSnake->dir);
 		if (get_pixel(pxTest))
 		{
 			for (uint8_t j = 0; j < pApples->nAppleCount; ++j)
@@ -294,8 +318,8 @@ static void snake_autoRoute(snake_protagonist_t *pprotSnake,
 
 
 /**
- * Small animation that lets the dying snake disappear.
+ * Small animation that lets the dying snake disappear piece by piece.
- * @param pprotSnake Pointer to the dying snake.
+ * @param pprotSnake A pointer to the dying snake.
  */
 static void snake_eliminateProtagonist(snake_protagonist_t *pprotSnake)
 {
@@ -310,7 +334,7 @@ static void snake_eliminateProtagonist(snake_protagonist_t *pprotSnake)
 
 /**
  * Initializes the structure that keeps track of all currently existing apples.
- * @param pApples Pointer to the apples in question.
+ * @param pApples Pointer to the set of apples in question.
  */
 static void snake_initApples(snake_apples_t *pApples)
 {
@@ -320,7 +344,7 @@ static void snake_initApples(snake_apples_t *pApples)
 
 /**
  * Checks for an apple at a given position and removes it if there is one.
- * @param pApples The set of apples which are one the playing field
+ * @param pApples The set of apples which are lying on the playing field.
  * @param pxHead The position to be tested.
  * @return 0 if no apples were found, 1 otherwise
  */
@@ -345,7 +369,7 @@ static uint8_t snake_checkForApple(snake_apples_t *pApples, pixel pxHead)
 
 /**
  * Creates some new apples from time to time.
- * @param pApples Pointer to the apple structure.
+ * @param pApples Pointer to a set of apples.
  */
 static void snake_spawnApples(snake_apples_t *pApples)
 {
@@ -362,7 +386,9 @@ static void snake_spawnApples(snake_apples_t *pApples)
 
 
 /**
- * The snake game.
+ * The main loop (plus initialization) that both drives the game and the
+ * demo mode.
+ * @param bDemoMode 0 indicates game mode, 1 indicates demo mode
  */
 void snake_engine(uint8_t bDemoMode)
 {
@@ -399,7 +425,7 @@ void snake_engine(uint8_t bDemoMode)
 		pixel pxOldHead = protSnake.aSegments[protSnake.nHeadIndex];
 		protSnake.nHeadIndex = (protSnake.nHeadIndex + 1) % USNAKE_MAX_LENGTH;
 		protSnake.aSegments[protSnake.nHeadIndex] =
-				snake_applyDirection(pxOldHead, protSnake.dir);
+				snake_nextDirection(pxOldHead, protSnake.dir);
 
 		// look if we have found an apple
 		if (!snake_checkForApple(&apples,
@@ -440,3 +466,5 @@ void snake_game(void)
 {
 	snake_engine(0);
 }
+
+/*@}*/

games/snake/snake_game.h

@@ -1,3 +1,15 @@
+/**
+ * \addtogroup Snake
+ *
+ * @{
+ */
+
+/**
+ * @file snake_game.h
+ * @brief Public interface of the snake game engine.
+ * @author Peter Fuhrmann, Martin Ongsiek, Daniel Otte, Christian Kroll
+ */
+
 #ifndef SNAKE_GAME_H_
 #define SNAKE_GAME_H_
 
@@ -7,3 +19,5 @@ void snake_engine(uint8_t bDemoMode);
 void snake_game(void);
 
 #endif /* SNAKE_GAME_H_ */
+
+/*@}*/

games/tetris/bearing.h

@@ -1,19 +1,37 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file bearing.h
+ * @brief Public interface for denoting the current bearing of the bucket.
+ * @author Christian Kroll
+ */
+
+
 #ifndef BEARING_H_
 #define BEARING_H_
 
 #include <stdint.h>
 
-enum tetris_bearing
+/**
+ * Denotes the bearing of the bucket.
+ */
+enum tetris_bearing_e
 {
-	TETRIS_BEARING_0,
+	TETRIS_BEARING_0,  //!< TETRIS_BEARING_0
-	TETRIS_BEARING_90,
+	TETRIS_BEARING_90, //!< TETRIS_BEARING_90
-	TETRIS_BEARING_180,
+	TETRIS_BEARING_180,//!< TETRIS_BEARING_180
-	TETRIS_BEARING_270
+	TETRIS_BEARING_270 //!< TETRIS_BEARING_270
 };
 #ifdef NDEBUG
 	typedef uint8_t tetris_bearing_t;
 #else
-	typedef enum tetris_bearing tetris_bearing_t;
+	typedef enum tetris_bearing_e tetris_bearing_t;
 #endif
 
+
 #endif /* BEARING_H_ */
+
+/*@}*/

games/tetris/bucket.c

@@ -1,3 +1,14 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file bucket.c
+ * @brief Implementation of Tetris' game logic.
+ * @author Christian Kroll
+ */
+
 #include <stdlib.h>
 #include <string.h>
 #include <assert.h>
@@ -7,7 +18,6 @@
 #include "bucket.h"
 #include "piece.h"
 
-
 /***************************
  * non-interface functions *
  ***************************/
@@ -498,3 +508,4 @@ uint16_t* tetris_bucket_predictNextRow(tetris_bucket_iterator_t *pIt)
 }
 
 #endif /* GAME_BASTET */
+/*@}*/

games/tetris/bucket.h

@@ -1,3 +1,15 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file bucket.h
+ * @brief Public interface definitions of Tetris' game logic module.
+ * @author Christian Kroll
+ */
+
+
 #ifndef BUCKET_H_
 #define BUCKET_H_
 
@@ -23,7 +35,7 @@
  *********/
 
 // directions to which a piece can be moved
-enum tetris_bucket_direction
+enum tetris_bucket_direction_e
 {
 	TETRIS_BUD_LEFT  = -1,
 	TETRIS_BUD_RIGHT = 1
@@ -31,12 +43,12 @@ enum tetris_bucket_direction
 #ifdef NDEBUG
 	typedef int8_t tetris_bucket_direction_t;
 #else
-	typedef enum tetris_bucket_direction tetris_bucket_direction_t;
+	typedef enum tetris_bucket_direction_e tetris_bucket_direction_t;
 #endif
 
 
 // status of the bucket
-enum tetris_bucket_status
+enum tetris_bucket_status_e
 {
 	TETRIS_BUS_HOVERING = 0, /** piece is hovering */
 	TETRIS_BUS_GLIDING  = 1, /** piece is gliding on the dump */
@@ -47,12 +59,12 @@ enum tetris_bucket_status
 #ifdef NDEBUG
 	typedef uint8_t tetris_bucket_status_t;
 #else
-	typedef enum tetris_bucket_status tetris_bucket_status_t;
+	typedef enum tetris_bucket_status_e tetris_bucket_status_t;
 #endif
 
 
 // tetris_bucket_t
-typedef struct tetris_bucket
+typedef struct tetris_bucket_s
 {
 	int8_t nWidth;                  /** width of bucket */
 	int8_t nHeight;                 /** height of bucket */
@@ -69,7 +81,7 @@ tetris_bucket_t;
 
 
 // iterator for predicted dump rows
-typedef struct tetris_bucket_iterator
+typedef struct tetris_bucket_iterator_s
 {
 	tetris_bucket_t *pBucket; /** bucket to be examined */
 	uint16_t nPieceMap;       /** piece bitmap */
@@ -330,7 +342,7 @@ int8_t tetris_bucket_predictDeepestRow(tetris_bucket_t *pBucket,
  * @param pPiece the piece which should be tested
  * @param nRow the row where the given piece collides
  * @param nColumn the column where the piece should be dropped
- * @return amount of complete lines
+ * @return number of complete lines
  */
 int8_t tetris_bucket_predictCompleteLines(tetris_bucket_t *pBucket,
                                           tetris_piece_t *pPiece,
@@ -364,3 +376,5 @@ uint16_t *tetris_bucket_predictNextRow(tetris_bucket_iterator_t *pIt);
 #endif /* GAME_BASTET */
 
 #endif /*BUCKET_H_*/
+
+/*@}*/

games/tetris/highscore.c

@@ -1,3 +1,15 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file highscore.c
+ * @brief Implementation of the high score table input module.
+ * @author Michael Holzt, Christian Kroll
+ */
+
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>
@@ -9,6 +21,7 @@
 #include "highscore.h"
 
 
+/** The global high score table (located in the EEPROM), */
 tetris_highscore_table_t g_highScoreTable EEMEM;
 
 
@@ -100,3 +113,5 @@ uint16_t tetris_highscore_retrieveHighScore(tetris_highscore_index_t nIndex)
 	// a score of 65535 is most likely caused by uninitialized EEPROM addresses
 	return nHighScore == UINT16_MAX ? 0 : nHighScore;
 }
+
+/*@}*/

games/tetris/highscore.h

@@ -1,3 +1,15 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file highscore.h
+ * @brief Public interface definitions of the high score table input module.
+ * @author Michael Holzt, Christian Kroll
+ */
+
+
 #ifndef TETRIS_HIGHSCORE_H_
 #define TETRIS_HIGHSCORE_H_
 
@@ -100,3 +112,5 @@ void tetris_highscore_saveHighScoreName(tetris_highscore_index_t nIndex,
 
 
 #endif /*TETRIS_HIGHSCORE_H_*/
+
+/*@}*/

games/tetris/input.c

@@ -1,3 +1,15 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file input.c
+ * @brief Implementation of the input routines of Tetris.
+ * @author Christian Kroll
+ */
+
+
 #include <stdlib.h>
 #include <stdint.h>
 #include <string.h>
@@ -8,30 +20,27 @@
 #include "bearing.h"
 #include "input.h"
 
-#define WAIT(ms) wait(ms)
-#define PM(value) pgm_read_byte(&value)
-
-/**
- * \defgroup TetrisInputDefinesPrivate Input: Internal constants
- */
-/*@{*/
 
 /***********
  * defines *
  ***********/
 
-/** amount of milliseconds that each loop cycle waits */
+#define WAIT(ms) wait(ms)
+#define PM(value) pgm_read_byte(&value)
+
+/** Number of milliseconds that each loop cycle waits. */
 #define TETRIS_INPUT_TICKS 5
 
 /**
- * amount of milliseconds the input is ignored after the pause combo has been
+ * Number of milliseconds the input is ignored after the pause key combination
- * pressed, since it is difficult to release all buttons simultaneously
+ * has been pressed, since it is difficult to release all buttons
+ * simultaneously.
  */
 #define TETRIS_INPUT_PAUSE_TICKS 100
 
 /**
- * amount of allowed loop cycles while in pause mode so that the game
+ * Number of allowed loop cycles while in pause mode so that the game
- * automatically continues after five minutes
+ * automatically continues after five minutes.
  */
 #define TETRIS_INPUT_PAUSE_CYCLES 60000
 
@@ -40,29 +49,23 @@
 /** delay (in loop cycles) for key repeat */
 #define TETRIS_INPUT_REPEAT_DELAY 5
 
-/** amount of loop cyles the left button is ignored */
+/** Number of loop cyles the left button is ignored */
 #define TETRIS_INPUT_CHATTER_TICKS_LEFT    12
-/** amount of loop cyles the right button is ignored */
+/** Number of loop cyles the right button is ignored */
 #define TETRIS_INPUT_CHATTER_TICKS_RIGHT   12
-/** amount of loop cyles the down button is ignored */
+/** Number of loop cyles the down button is ignored */
 #define TETRIS_INPUT_CHATTER_TICKS_DOWN    12
-/** amount of loop cyles the clockwise rotation button is ignored */
+/** Number of loop cyles the clockwise rotation button is ignored */
 #define TETRIS_INPUT_CHATTER_TICKS_ROT_CW  24
-/** amount of loop cyles the counter clockwise rotation button is ignored */
+/** Number of loop cyles the counter clockwise rotation button is ignored */
 #define TETRIS_INPUT_CHATTER_TICKS_ROT_CCW 24
-/** amount of loop cyles the drop button is ignored */
+/** Number of loop cyles the drop button is ignored */
 #define TETRIS_INPUT_CHATTER_TICKS_DROP    36
 
 /** wait cycles per level (array of uint8_t) */
 #define TETRIS_INPUT_LVL_CYCLES 200, 133, 100, 80, 66, 57, 50, 44, 40, 36, 33, \
 	30, 28, 26, 25, 23, 22, 21, 20, 19, 18, 17, 16, 15, 14, 13, 12, 11, 10, 9
 
-/*@}*/
-
-/**
- * \defgroup TetrisInputNoInterface Input: Internal non-interface functions
- */
-/*@{*/
 
 /***************************
  * non-interface functions *
@@ -79,7 +82,7 @@ static void tetris_input_chatterProtect(tetris_input_t *pIn,
 	// never exceed the index
 	assert(cmd < TETRIS_INCMD_NONE);
 
-	// amount of loop cycles a command is ignored after its button has been
+	// number of loop cycles a command is ignored after its button has been
 	// released (every command has its own counter)
 	static uint8_t const nInitialIgnoreValue[TETRIS_INCMD_NONE] PROGMEM =
 	{
@@ -214,8 +217,6 @@ static tetris_input_command_t tetris_input_queryJoystick(tetris_input_t *pIn)
 	return cmdReturn;
 }
 
-/*@}*/
-
 
 /****************************
  * construction/destruction *
@@ -384,3 +385,5 @@ void tetris_input_setBearing(tetris_input_t *pIn,
 	// changes its meaning as soon as the bearing changes
 	pIn->cmdLast = tetris_input_mapCommand(pIn->nBearing, pIn->cmdRawLast);
 }
+
+/*@}*/

games/tetris/input.h

@@ -1,3 +1,15 @@
+/**
+ * \addtogroup tetris
+ *@{
+ */
+
+/**
+ * @file input.h
+ * @brief Public interface definitions of the input module of Tetris.
+ * @author Christian Kroll
+ */
+
+
 #ifndef INPUT_H_
 #define INPUT_H_
 
@@ -6,10 +18,6 @@
 #include <assert.h>
 #include "bearing.h"
 
-/**
- * \defgroup TetrisInputDefinesPublic Input: Public constants
- */
-/*@{*/
 
 /***********
  * defines *
@@ -18,13 +26,6 @@
 /** number of levels */
 #define TETRIS_INPUT_LEVELS 30
 
-/*@}*/
-
-
-/**
- * \defgroup TetrisInputTypes Input: Data types
- */
-/*@{*/
 
 /*********
  * types *
@@ -33,7 +34,7 @@
 /**
  * allowed input values
  */
-enum tetris_input_command
+enum tetris_input_command_e
 {
 	TETRIS_INCMD_RIGHT,   /**< move piece right */
 	TETRIS_INCMD_DOWN,    /**< lower piece by one row */
@@ -48,14 +49,14 @@ enum tetris_input_command
 #ifdef NDEBUG
 	typedef uint8_t tetris_input_command_t;
 #else
-	typedef enum tetris_input_command tetris_input_command_t;
+	typedef enum tetris_input_command_e tetris_input_command_t;
 #endif
 
 
 /**
  * values which influence the gravity time limit for a piece
  */
-enum tetris_input_pace
+enum tetris_input_pace_e
 {
 	TETRIS_INPACE_HOVERING = 0, /**< normal falling pace */
 	TETRIS_INPACE_GLIDING  = 75 /**< guarantees a minimum docking time to avoid
@@ -64,17 +65,17 @@ enum tetris_input_pace
 #ifdef NDEBUG
 	typedef uint8_t tetris_input_pace_t;
 #else
-	typedef enum tetris_input_pace tetris_input_pace_t;
+	typedef enum tetris_input_pace_e tetris_input_pace_t;
 #endif
 
 
 /**
  * data structure for the input module
  */
-typedef struct tetris_input
+typedef struct tetris_input_s
 {
 	/**
-	 * Amount of loop cycles between forced piece movements. This value gets
+	 * Number of loop cycles between forced piece movements. This value gets
 	 * set via the tetris_input_setLevel() function.
 	 */
 	uint8_t nMaxCycles;
@@ -88,7 +89,7 @@ typedef struct tetris_input
 	uint8_t nLoopCycles;
 
 	/**
-	 * Amount of loop cycles in which the same command has been issued
+	 * Number of loop cycles in which the same command has been issued
 	 * consecutively. It gets reset if either the current command differs from
 	 * the last one or a well-defined value has been reached (thereby
 	 * regulating the pace of the key repeat as commands are only processed
@@ -131,13 +132,6 @@ typedef struct tetris_input
 }
 tetris_input_t;
 
-/*@}*/
-
-
-/**
- * \defgroup TetrisInputRelated Input: Interface functions
- */
-/*@{*/
 
 /****************************
  * construction/destruction *
@@ -200,6 +194,6 @@ void tetris_input_resetDownKeyRepeat(tetris_input_t *pIn);
 void tetris_input_setBearing(tetris_input_t *pIn,
                              tetris_bearing_t nBearing);
 
-/*@}*/
-
 #endif /*INPUT_H_*/
+
+/*@}*/

games/tetris/piece.c

@@ -1,3 +1,15 @@
+/**
+ * \addtogroup tetris
+ *@{
+ */
+
+/**
+ * @file piece.c
+ * @brief Implementation of the piece module.
+ * @author Christian Kroll
+ */
+
+
 #include <stdlib.h>
 #include <assert.h>
 #include <stdint.h>
@@ -55,3 +67,5 @@ uint8_t tetris_piece_getAngleCount(tetris_piece_t *pPc)
 
 	return pgm_read_byte(&angleCounts[pPc->shape]);
 }
+
+/*@}*/

games/tetris/piece.h

@@ -1,3 +1,15 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file piece.h
+ * @brief Public interface definitions of the piece module.
+ * @author Christian Kroll
+ */
+
+
 #ifndef TETRIS_PIECE_H_
 #define TETRIS_PIECE_H_
 
@@ -5,17 +17,13 @@
 #include <stdlib.h>
 #include <assert.h>
 
-/**
- * \defgroup TetrisPieceTypes Piece: Data types
- */
-/*@{*/
 
 /*********
  * types *
  *********/
 
 /** shape attributes for a piece */
-enum tetris_piece_shape
+enum tetris_piece_shape_e
 {
 	TETRIS_PC_LINE,   /**< the I shaped brick */
 	TETRIS_PC_T,      /**< the T shaped brick */
@@ -28,12 +36,12 @@ enum tetris_piece_shape
 #ifdef NDEBUG
 	typedef uint8_t tetris_piece_shape_t;
 #else
-	typedef enum tetris_piece_shape tetris_piece_shape_t;
+	typedef enum tetris_piece_shape_e tetris_piece_shape_t;
 #endif
 
 
 /** possible angles for a brick */
-enum tetris_piece_angle
+enum tetris_piece_angle_e
 {
 	TETRIS_PC_ANGLE_0,   /**< standard angle */
 	TETRIS_PC_ANGLE_90,  /**< rotated by 90 degrees */
@@ -43,11 +51,11 @@ enum tetris_piece_angle
 #ifdef NDEBUG
 	typedef uint8_t tetris_piece_angle_t;
 #else
-	typedef enum tetris_piece_angle tetris_piece_angle_t;
+	typedef enum tetris_piece_angle_e tetris_piece_angle_t;
 #endif
 
 /** rotation attributes */
-enum tetris_piece_rotation
+enum tetris_piece_rotation_e
 {
 	TETRIS_PC_ROT_CW  = 1, /**< clockwise rotation */
 	TETRIS_PC_ROT_CCW = 3  /**< counter clockwise rotation */
@@ -55,7 +63,7 @@ enum tetris_piece_rotation
 #ifdef NDEBUG
 	typedef uint8_t tetris_piece_rotation_t;
 #else
-	typedef enum tetris_piece_rotation tetris_piece_rotation_t;
+	typedef enum tetris_piece_rotation_e tetris_piece_rotation_t;
 #endif
 
 /**
@@ -63,20 +71,13 @@ enum tetris_piece_rotation
  * @see tetris_piece_shape_t
  * @see tetris_piece_angle_t
  */
-typedef struct tetris_piece
+typedef struct tetris_piece_s
 {
 	tetris_piece_shape_t shape; /**< specifies the shape of the piece */
 	tetris_piece_angle_t angle; /**< specifies one of 4 angels */
 }
 tetris_piece_t;
 
-/*@}*/
-
-
-/**
- * \defgroup TetrisPieceRelated Piece: Interface functions
- */
-/*@{*/
 
 /*****************************
  *  construction/destruction *
@@ -215,6 +216,6 @@ inline static int8_t tetris_piece_getBottomOffset(uint16_t const nBitmap)
 	return 0;     // last three rows of the piece are empty
 }
 
-/*@}*/
-
 #endif /*TETRIS_PIECE_H_*/
+
+/*@}*/

games/tetris/tetris_main.c

@@ -1,3 +1,14 @@
+/**
+ * \defgroup tetris Tetris, the popular puzzle game.
+ * @{
+ */
+
+/**
+ * @file tetris_main.c
+ * @brief Main loop of the Tetris module.
+ * @author Christian Kroll
+ */
+
 #include <stdlib.h>
 #include <assert.h>
 #include <stdint.h>
@@ -10,7 +21,6 @@
 #include "view.h"
 #include "tetris_main.h"
 
-
 void tetris_main(tetris_variant_t const *const pVariantMethods)
 {
 	// get view dependent dimensions of the bucket
@@ -206,3 +216,5 @@ void tetris_main(tetris_variant_t const *const pVariantMethods)
 	tetris_bucket_destruct(pBucket);
 	tetris_piece_destruct(pPiece);
 }
+
+/*@}*/

games/tetris/tetris_main.h

@@ -1,3 +1,14 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file tetris_main.h
+ * @brief Public prototype of Tetris' main loop function.
+ * @author Christian Kroll
+ */
+
 #ifndef TETRIS_MAIN_H_
 #define TETRIS_MAIN_H_
 
@@ -10,5 +21,6 @@
  */
 void tetris_main(tetris_variant_t const *const pVariantMethods);
 
-
 #endif /* TETRIS_MAIN_H_ */
+
+/*@}*/

games/tetris/variant_bastet.c

@@ -1,3 +1,20 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file variant_bastet.c
+ * @brief Implementation of the "Bastard Tetris" module.
+ * @details Based on the game "Bastet" (version 0.41) by Frederico Poloni. His
+ *          code isn't used as the Borg's Tetris framework is too different from
+ *          that of "Petris" (on which Bastet is based), but the algorithms of
+ *          this implementation are closely modeled after his ideas.
+ * @author Christian Kroll
+ * @see Frederico Poloni's homepage: http://fph.altervista.org/prog/bastet.html
+ */
+
+
 #include <stdlib.h>
 #include <string.h>
 #include <assert.h>
@@ -514,3 +531,5 @@ tetris_bearing_t tetris_bastet_getBearing(void *pVariantData)
 {
 	return TETRIS_BEARING_0;
 }
+
+/*@}*/

games/tetris/variant_bastet.h

@@ -1,3 +1,20 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file variant_bastet.h
+ * @brief Public interface of the "Bastard Tetris" module.
+ * @details Based on the game "Bastet" (version 0.41) by Frederico Poloni. His
+ *          code isn't used as the Borg's Tetris framework is too different from
+ *          that of "Petris" (on which Bastet is based), but the algorithms of
+ *          this implementation are closely modeled after his ideas.
+ * @author Christian Kroll
+ * @see Frederico Poloni's homepage: http://fph.altervista.org/prog/bastet.html
+ */
+
+
 #ifndef VARIANT_BASTET_H_
 #define VARIANT_BASTET_H_
 
@@ -9,6 +26,7 @@
 #include "input.h"
 #include "variants.h"
 
+
 /***************
  * entry point *
  ***************/
@@ -23,7 +41,7 @@ void tetris_bastet(void);
  * types *
  *********/
 
-typedef struct tetris_bastet_scorepair
+typedef struct tetris_bastet_scorepair_s
 {
 	tetris_piece_shape_t shape;
 	int16_t nScore;
@@ -31,10 +49,10 @@ typedef struct tetris_bastet_scorepair
 tetris_bastet_scorepair_t;
 
 
-typedef struct tetris_bastet_variant
+typedef struct tetris_bastet_variant_s
 {
 	uint16_t nScore;                          /** score of the player */
-	uint16_t nHighscore;                      /** highscore */
+	uint16_t nHighscore;                      /** high score */
 	uint16_t nHighscoreName;                  /** champion's initials */
 	uint8_t nLevel;                           /** current level */
 	uint16_t nLines;                          /** number of completed lines */
@@ -210,3 +228,5 @@ void tetris_bastet_setLastInput(void *pVariantData,
 tetris_bearing_t tetris_bastet_getBearing(void *pVariantData);
 
 #endif /*VARIANT_BASTET_H_*/
+
+/*@}*/

games/tetris/variant_fp.c

@@ -1,3 +1,21 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file variant_fp.c
+ * @brief Implementation of the "First Person Tetris" module.
+ * @details Originally implemented by Michael Holzt. However, his implementation
+ *          did not quite fit into this framework anymore as it was heavily
+ *          modified to improve modularization. Therefore, his code got replaced
+ *          completely. Sorry about that, but thanks for the original
+ *          implementation nonetheless!
+ * @author Christian Kroll
+ * @see variant_std.c
+ */
+
+
 #include <stdlib.h>
 #include <assert.h>
 #include <stdint.h>
@@ -102,3 +120,5 @@ void tetris_fp_setLastInput(void *pVariantData,
 	}
 	pStdVariant->nBearing %= 4;
 }
+
+/*@}*/

games/tetris/variant_fp.h

@@ -1,3 +1,20 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file variant_fp.h
+ * @brief Public interface of the "First Person Tetris" module.
+ * @details Originally implemented by Michael Holzt. However, his implementation
+ *          did not quite fit into this framework anymore as it was heavily
+ *          modified to improve modularization. Therefore, his code got replaced
+ *          completely. Sorry about that, but thanks for the original
+ *          implementation nonetheless!
+ * @author Christian Kroll
+ * @see variant_std.h
+ */
+
 #ifndef VARIANT_FP_H_
 #define VARIANT_FP_H_
 
@@ -26,7 +43,7 @@ tetris_variant_t const tetrisFpVariant;
 
 
 /**
- * retrieves the variant's highscore index
+ * retrieves the variant's high score index
  * @param pVariantData the variant data object we want information from
  */
 tetris_highscore_index_t tetris_fp_getHighscoreIndex(void *pVariantData);
@@ -43,3 +60,5 @@ void tetris_fp_setLastInput(void *pVariantData,
                             uint8_t bMoveOk);
 
 #endif /*VARIANT_FP_H_*/
+
+/*@}*/

games/tetris/variant_std.c

@@ -1,3 +1,18 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file variant_std.c
+ * @brief Implementation of the standard Tetris module.
+ * @details The routines of this file provide selection of new pieces, line
+ *          counting, score calculation, high score management, adjustment of
+ *          the bucket's bearing and so on.
+ * @author Christian Kroll
+ */
+
+
 #include <stdlib.h>
 #include <string.h>
 #include <assert.h>
@@ -255,3 +270,5 @@ tetris_bearing_t tetris_std_getBearing(void *pVariantData)
 
 	return pStdVariant->nBearing;
 }
+
+/*@}*/

games/tetris/variant_std.h

@@ -1,3 +1,15 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file variant_std.h
+ * @brief Public interface of the standard Tetris module.
+ * @author Christian Kroll
+ */
+
+
 #ifndef VARIANT_STD_H_
 #define VARIANT_STD_H_
 
@@ -25,7 +37,7 @@ void tetris(void);
  * types *
  *********/
 
-typedef struct tetris_standard_variant_t
+typedef struct tetris_standard_variant_s
 {
 	uint16_t nScore;               /** score of the player */
 	uint16_t nHighscore;           /** highscore */
@@ -193,3 +205,5 @@ void tetris_std_setLastInput(void *pVariantData,
 tetris_bearing_t tetris_std_getBearing(void *pVariantData);
 
 #endif /*VARIANT_STD_H_*/
+
+/*@}*/

games/tetris/variants.h

@@ -1,3 +1,19 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file variants.h
+ * @brief Public interface of a Tetris variant.
+ * @details This header file describes a struct containing function pointers
+ *          that every Tetris variant has to implement. It resembles an abstract
+ *          C++ class whose virtual methods need to be implemented.
+ * @author Christian Kroll
+ * @see Have a look at variant_std.c which not only implements a fairly standard
+ *      Tetris variant but also serves as an example for new variants to come!
+ */
+
 #ifndef VARIANTS_H_
 #define VARIANTS_H_
 
@@ -8,7 +24,8 @@
 #include "bucket.h"
 #include "input.h"
 
-typedef struct tetris_variant
+
+typedef struct tetris_variant_s
 {
 	/**
 	 * constructs a variant data object
@@ -148,4 +165,6 @@ typedef struct tetris_variant
 }
 tetris_variant_t;
 
+/*@}*/
+
 #endif /*VARIANTS_H_*/

games/tetris/view.c

@@ -1,3 +1,15 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file view.c
+ * @brief Implementation of Tetris' graphical output routines.
+ * @author Christian Kroll
+ */
+
+
 #include <stdlib.h>
 #include <stdio.h>
 #include <string.h>
@@ -13,11 +25,6 @@
 #include "view.h"
 
 
-/**
- * \defgroup TetrisViewDefinesPrivate View: Internal constants
- */
-/*@{*/
-
 /***********
  * defines *
  ***********/
@@ -103,13 +110,6 @@
 #endif
 
 
-/*@}*/
-
-
-/**
- * \defgroup TetrisViewNoInterface View: Internal non-interface functions
- */
-/*@{*/
 
 /***************************
  * non-interface functions *
@@ -568,7 +568,6 @@ static void tetris_view_formatHighscoreName(uint16_t nHighscoreName,
 	}
 	pszName[3] = '\0';
 }
-/*@}*/
 
 
 /****************************
@@ -674,3 +673,5 @@ void tetris_view_showResults(tetris_view_t *pV)
 	scrolltext(pszResults);
 #endif
 }
+
+/*@}*/

games/tetris/view.h

@@ -1,3 +1,15 @@
+/**
+ * \addtogroup tetris
+ * @{
+ */
+
+/**
+ * @file view.c
+ * @brief Public interface definitions of Tetris' graphical output routines.
+ * @author Christian Kroll
+ */
+
+
 #ifndef TETRIS_VIEW_H_
 #define TETRIS_VIEW_H_
 
@@ -7,17 +19,12 @@
 #include "variants.h"
 
 
-/**
- * \defgroup TetrisViewTypes View: Data types
- */
-/*@{*/
-
 /*********
  * types *
  *********/
 
 /** presentation modes */
-enum tetris_view_mode
+enum tetris_view_mode_e
 {
 	TETRIS_VIMO_PAUSED,
 	TETRIS_VIMO_RUNNING
@@ -25,12 +32,12 @@ enum tetris_view_mode
 #ifdef NDEBUG
 	typedef uint8_t tetris_view_mode_t;
 #else
-	typedef enum tetris_view_mode tetris_view_mode_t;
+	typedef enum tetris_view_mode_e tetris_view_mode_t;
 #endif
 
 
 /** data structure that drives the view module */
-typedef struct tetris_view
+typedef struct tetris_view_s
 {
 	tetris_variant_t const *pVariantMethods; /** variant function pointers */
 	void *pVariant;                          /** associated variant object */
@@ -42,13 +49,6 @@ typedef struct tetris_view
 }
 tetris_view_t;
 
-/*@}*/
-
-
-/**
- * \defgroup TetrisInterface View: Interface functions
- */
-/*@{*/
 
 /*****************************
  *  construction/destruction *