Properly documented everything (including the new DraciFont class). Reshuffled some old comments.

svn-id: r41467

5 files changed, 119 insertions, 38 deletions

diff --git a/engines/draci/barchive.h b/engines/draci/barchive.h
index 0a0ecc832b..683ec50a67 100644
--- a/engines/draci/barchive.h
+++ b/engines/draci/barchive.h
@@ -31,7 +31,7 @@
 namespace Draci {
 
 /**
- *  Represents individual files inside the archive
+ *  Represents individual files inside the archive.
  */
 
 struct BAFile {
@@ -40,7 +40,8 @@ struct BAFile {
 	byte *_data;
 	byte _crc;
 
-	void closeFile(void) { //!< Releases the file data (for memory considerations)
+	/** Releases the file data (for memory considerations) */
+	void closeFile(void) {  
 		delete _data;
 		_data = NULL;
 	}
diff --git a/engines/draci/font.cpp b/engines/draci/font.cpp
index d1c5eaa3be..5ea46ddb17 100644
--- a/engines/draci/font.cpp
+++ b/engines/draci/font.cpp
@@ -33,13 +33,30 @@ namespace Draci {
 DraciFont::DraciFont(Common::String &filename) : 
 	_fontHeight(0), _maxCharWidth(0), 
 	_charWidths(NULL), _charData(0) { 
-	setFont(filename); 
+	setFont(filename);
 }
 
 DraciFont::~DraciFont() {
 	 freeFont(); 
 }
 
+/**
+ * @brief Loads fonts from a file
+ * @param path Path to font file
+ * @return true if the font was loaded successfully, false otherwise
+ *
+ * Loads fonts from a file into a DraciFont instance. The original game uses two
+ * fonts (located inside files "Small.fon" and "Big.fon"). The characters in the
+ * font are indexed from the ASCII space (decimal value 32) so an appropriate
+ * offset must be added to convert them to equivalent char values, 
+ * i.e. kDraciIndexOffset.
+ *
+ * font format: [1 byte] maximum character width
+ *				[1 byte] font height
+ *				[138 bytes] character widths of all 138 characters in the font
+ *				[138 * fontHeight * maxWidth bytes] character data, stored row-wise 
+ */
+
 bool DraciFont::setFont(Common::String &filename) {
 	
 	// If there is a font already loaded, free it
@@ -89,6 +106,14 @@ uint8 DraciFont::getCharWidth(uint8 chr) const {
 	return _charWidths[chr - kCharIndexOffset];
 }
 
+/**
+ * @brief Draw a char to a Graphics::Surface
+ * @param dst 	Pointer to the destination surface
+ * @param chr 	Character to draw (ASCII value)
+ * @param tx  	Horizontal offset on the surface
+ * @param ty  	Vertical offset on the surface
+ */
+
 void DraciFont::drawChar(Graphics::Surface *dst, uint8 chr, int tx, int ty) const {
 	assert(dst != NULL);
 	byte *ptr = (byte *)dst->getBasePtr(tx, ty);
@@ -120,6 +145,16 @@ void DraciFont::drawChar(Graphics::Surface *dst, uint8 chr, int tx, int ty) cons
 	}
 }
 
+/**
+ * @brief Draw a string to a Graphics::Surface
+ *
+ * @param dst 		Pointer to the destination surface
+ * @param str 		String to draw
+ * @param x  		Horizontal offset on the surface
+ * @param y  		Vertical offset on the surface
+ * @param spacing 	Space to leave between individual characters. Defaults to 0. 
+ */
+
 void DraciFont::drawString(Graphics::Surface *dst, Common::String str, 
 							int x, int y, int spacing) const {
 	assert(dst != NULL);	
@@ -131,6 +166,15 @@ void DraciFont::drawString(Graphics::Surface *dst, Common::String str,
 	}
 }
 
+/**
+ * @brief Calculate the width of a string when drawn in the current font
+ *
+ * @param str 		String to draw
+ * @param spacing	Space to leave between individual characters. Defaults to 0. 
+ *
+ * @return The calculated width of the string 
+ */
+
 int DraciFont::getStringWidth(Common::String &str, int spacing) const {
 	int width = 0;	
 	uint len = str.size();
diff --git a/engines/draci/font.h b/engines/draci/font.h
index 246bb4cc9f..d74951c783 100644
--- a/engines/draci/font.h
+++ b/engines/draci/font.h
@@ -27,6 +27,10 @@
 
 namespace Draci {
 
+/**
+ *  Represents the game's fonts. See docs for setFont() for font format details.
+ */
+
 class DraciFont {
 	
 public: 
@@ -44,15 +48,20 @@ public:
 private:
 	uint8 _fontHeight;
 	uint8 _maxCharWidth;
+	
+	/** Pointer to an array of individual char widths */	
 	uint8 *_charWidths;
+	
+	/** Pointer to a raw byte array representing font pixels stored row-wise */
 	byte *_charData;
 	
-	// Number of glyphs in the font
+	/** Number of glyphs in the font */
 	static const unsigned int kCharNum = 138;
 
-	// Chars are indexed from the ASCII space (decimal value 32)
+	/** Chars are indexed from the ASCII space (decimal value 32) */
 	static const unsigned int kCharIndexOffset = 32;
 
+	/** Internal function for freeing fonts when destructing/loading another */
 	void freeFont();
 };
 
diff --git a/engines/draci/gpldisasm.cpp b/engines/draci/gpldisasm.cpp
index 9024a2dd72..17ed5c7494 100644
--- a/engines/draci/gpldisasm.cpp
+++ b/engines/draci/gpldisasm.cpp
@@ -23,37 +23,6 @@
  *
  */
 
-/**
- * @brief GPL2 bytecode disassembler
- * @param gplcode A pointer to the bytecode
- *        len Length of the bytecode
- *
- * GPL2 is short for Game Programming Language 2 which is the script language
- * used by Draci Historie. This is a simple disassembler for the language.
- *
- * A compiled GPL2 program consists of a stream of bytes representing commands
- * and their parameters. The syntax is as follows:
- *
- * Syntax of a command:
- *	<name of the command> <number> <sub-number> <list of parameters...>
- *
- *	Syntax of a parameter:
- *	- 1: integer number literally passed to the program
- *	- 2-1: string stored in the reservouir of game strings (i.e. something to be
- *	  displayed) and stored as an index in this list
- *	- 2-2: string resolved by the compiler (i.e., a path to another file) and
- *	  replaced by an integer index of this entity in the appropriate namespace
- *	  (e.g., the index of the palette, location, ...)
- *	- 3-0: relative jump to a label defined in this code.  Each label must be
- *	  first declared in the beginning of the program.
- *	- 3-1 .. 3-9: index of an entity in several namespaces, defined in file ident
- *	- 4: mathematical expression compiled into a postfix format
- *
- * 	In the compiled program, parameters of type 1..3 are represented by a single
- *	16-bit integer.  The called command knows by its definition what namespace the
- *	value comes from.
- */
-
 #include "common/debug.h"
 #include "common/stream.h"
 #include "common/stack.h"
@@ -64,6 +33,8 @@
 namespace Draci {
 
 // FIXME: Change parameter types to names once I figure out what they are exactly
+
+/** A table of all the commands the game player uses */
 GPL2Command gplCommands[] = {
 	{ 0,  0, "gplend",				0, { 0 } },
 	{ 0,  1, "exit",				0, { 0 } },
@@ -122,6 +93,7 @@ GPL2Command gplCommands[] = {
 	{ 27, 1, "FeedPassword", 		3, { 1, 1, 1 } }
 };
 
+/** Operators used by the mathematical evaluator */
 Common::String operators[] = {
 	"oper_and",
 	"oper_or",
@@ -139,6 +111,7 @@ Common::String operators[] = {
 	"oper_minus"
 };
 
+/** Functions used by the mathematical evaluator */
 Common::String functions[] = {
 	"F_Not",
 	"F_Random",
@@ -161,6 +134,7 @@ Common::String functions[] = {
 
 const unsigned int kNumCommands = sizeof gplCommands / sizeof gplCommands[0];
 
+/** Type of mathematical object */
 enum mathExpressionObject {
 	kMathEnd,
 	kMathNumber,
@@ -170,6 +144,12 @@ enum mathExpressionObject {
 };
 
 // FIXME: The evaluator is now complete but I still need to implement callbacks
+
+/**
+ * @brief Evaluates mathematical expressions
+ * @param reader Stream reader set to the beginning of the expression
+ */
+
 void handleMathExpression(Common::MemoryReadStream &reader) {
 	Common::Stack<uint16> stk;
 	mathExpressionObject obj;
@@ -224,6 +204,15 @@ void handleMathExpression(Common::MemoryReadStream &reader) {
 	return;
 }
 
+/**
+ * @brief Find the current command in the internal table
+ *
+ * @param num 		Command number
+ * @param subnum 	Command subnumer
+ *
+ * @return NULL if command is not found. Otherwise, a pointer to a GPL2Command
+ *         struct representing the command.
+ */
 GPL2Command *findCommand(byte num, byte subnum) {
 	unsigned int i = 0;
 	while (1) {
@@ -245,6 +234,37 @@ GPL2Command *findCommand(byte num, byte subnum) {
 	return NULL;
 }
 
+/**
+ * @brief GPL2 bytecode disassembler
+ * @param gplcode A pointer to the bytecode
+ * @param len Length of the bytecode
+ *
+ * GPL2 is short for Game Programming Language 2 which is the script language
+ * used by Draci Historie. This is a simple disassembler for the language.
+ *
+ * A compiled GPL2 program consists of a stream of bytes representing commands
+ * and their parameters. The syntax is as follows:
+ *
+ * Syntax of a command:
+ *	<name of the command> <number> <sub-number> <list of parameters...>
+ *
+ *	Syntax of a parameter:
+ *	- 1: integer number literally passed to the program
+ *	- 2-1: string stored in the reservouir of game strings (i.e. something to be
+ *	  displayed) and stored as an index in this list
+ *	- 2-2: string resolved by the compiler (i.e., a path to another file) and
+ *	  replaced by an integer index of this entity in the appropriate namespace
+ *	  (e.g., the index of the palette, location, ...)
+ *	- 3-0: relative jump to a label defined in this code.  Each label must be
+ *	  first declared in the beginning of the program.
+ *	- 3-1 .. 3-9: index of an entity in several namespaces, defined in file ident
+ *	- 4: mathematical expression compiled into a postfix format
+ *
+ * 	In the compiled program, parameters of type 1..3 are represented by a single
+ *	16-bit integer.  The called command knows by its definition what namespace the
+ *	value comes from.
+ */
+
 int gpldisasm(byte *gplcode, uint16 len) {
 	Common::MemoryReadStream reader(gplcode, len);
 
diff --git a/engines/draci/gpldisasm.h b/engines/draci/gpldisasm.h
index d26fb5c978..17bd75767d 100644
--- a/engines/draci/gpldisasm.h
+++ b/engines/draci/gpldisasm.h
@@ -30,7 +30,14 @@
 
 namespace Draci {
 
-// FIXME: Add parameter types and function handlers
+// FIXME: Add function handlers
+
+/**
+ *  Represents a single command in the GPL scripting language bytecode.
+ *	Each command is represented in the bytecode by a command number and a 
+ *	subnumber.
+ */
+
 struct GPL2Command { 
 	byte _number; 
 	byte _subNumber; 
@@ -39,7 +46,7 @@ struct GPL2Command {
 	int _paramTypes[3];
 };
 
-const int kMaxParams = 3;
+const int kMaxParams = 3; //!< The maximum number of parameters for a GPL command
 
 int gpldisasm(byte *gplcode, uint16 len);