GLK: ALAN2: Move comments to header files

4 files changed, 87 insertions, 37 deletions

diff --git a/engines/glk/alan2/decode.cpp b/engines/glk/alan2/decode.cpp
index aaf297b759..3a93d1d3a8 100644
--- a/engines/glk/alan2/decode.cpp
+++ b/engines/glk/alan2/decode.cpp
@@ -92,8 +92,6 @@ int Decode::decodeChar() {
 	return symbol - 1;
 }
 
-// Save so much about the decoding process, so it is possible to restore
-// and continue later.
 DecodeInfo *Decode::pushDecode() {
 	DecodeInfo *info = new DecodeInfo();
 
@@ -107,8 +105,6 @@ DecodeInfo *Decode::pushDecode() {
 	return info;
 }
 
-// Restore enough info about the decoding process, so it is possible to
-// continue after having decoded something else
 void Decode::popDecode (DecodeInfo *info) {
 	_txtFile->seek(info->fpos, SEEK_CUR);
 	_decodeBuffer = info->buffer;
diff --git a/engines/glk/alan2/decode.h b/engines/glk/alan2/decode.h
index 1361badfa1..75a35dc945 100644
--- a/engines/glk/alan2/decode.h
+++ b/engines/glk/alan2/decode.h
@@ -31,22 +31,33 @@ namespace Glk {
 namespace Alan2 {
 
 // Structure for saved decode info
-typedef struct DecodeInfo {
+struct DecodeInfo {
 	long fpos;
 	int buffer;
 	int bits;
 	CodeValue value;
 	CodeValue high;
 	CodeValue low;
-} DecodeInfo;
+};
 
 class Decode {
 public:
 	Decode(Common::File *txtFile, Aword *freq): _txtFile(txtFile), _freq(freq) {}
 	void startDecoding();
 	int decodeChar();
+	
+	/**
+	 * Save so much about the decoding process, so it is possible to restore
+	 * and continue later.
+	 */
 	DecodeInfo *pushDecode();
+	
+	/**
+	 * Restore enough info about the decoding process, so it is possible to
+	 * continue after having decoded something else.
+	 */
 	void popDecode(DecodeInfo *info);
+	
 	int inputBit();
 
 private:
@@ -64,6 +75,6 @@ private:
 };
 
 } // End of namespace Alan2
-} // Engine of namespace GLK
+} // End of namespace Glk
 
 #endif
diff --git a/engines/glk/alan2/parse.cpp b/engines/glk/alan2/parse.cpp
index 789080f936..45fac67f4f 100644
--- a/engines/glk/alan2/parse.cpp
+++ b/engines/glk/alan2/parse.cpp
@@ -216,7 +216,6 @@ void Parser::scan() {
 	} while (!eol);
 }
 
-// Search for a non-verb command
 void Parser::nonverb() {
 	if (isDir(wrds[wrdidx])) {
 		wrdidx++;
@@ -264,7 +263,6 @@ Abool Parser::isHere(Aword id) {
 
 // ----------------------------------------------------------------------------
 
-// Build a list of objects matching 'all'
 void Parser::buildall(ParamElem list[]) {
 	int o, i = 0;
 	bool found = false;
@@ -310,7 +308,6 @@ void Parser::listIntersection(ParamElem a[], ParamElem b[]) {
 	a[last].code = EOF;
 }
 
-// Copy the refs (in dictionary) to a paramList
 void Parser::listCopyFromDictionary(ParamElem p[], Aword r[]) {
 	int i;
 
@@ -331,7 +328,6 @@ int Parser::listLength(ParamElem a[]) {
 	return (i);
 }
 
-// Compact a list, i.e remove any NULL elements
 void Parser::listCompact(ParamElem a[]) {
 	int i, j;
 
@@ -342,7 +338,6 @@ void Parser::listCompact(ParamElem a[]) {
 	a[i].code = EOF;
 }
 
-// Merge the paramElems of one list into the first
 void Parser::listMerge(ParamElem a[], ParamElem b[]) {
 	int i, last;
 
@@ -356,7 +351,6 @@ void Parser::listMerge(ParamElem a[], ParamElem b[]) {
 	}
 }
 
-// Subtract two lists
 void Parser::listSubtract(ParamElem a[], ParamElem b[]) {
 	for (int i = 0; a[i].code != EOF; i++)
 		if (listContains(b, a[i].code))
@@ -365,7 +359,6 @@ void Parser::listSubtract(ParamElem a[], ParamElem b[]) {
 	listCompact(a);
 }
 
-// Match an unambigous object reference
 void Parser::unambig(ParamElem plst[]) {
 	int i;
 	bool found = false;		// Adjective or noun found?
@@ -485,7 +478,6 @@ void Parser::unambig(ParamElem plst[]) {
 	}
 }
 
-// Match a simple verb command
 void Parser::simple(ParamElem olst[]) {
 	static ParamElem *tlst = NULL;
 	int savidx = wrdidx;
@@ -541,7 +533,6 @@ void Parser::simple(ParamElem olst[]) {
 	}
 }
 
-// Match a complex verb command
 void Parser::complex(ParamElem olst[]) {
 	// Above this procedure we can use the is* tests, but not below since
 	// they work on words.Below all is converted to indices into the
@@ -595,8 +586,6 @@ bool Parser::claCheck(ClaElem *cla) {
 	return ok;
 }
 
-// In case the syntax did not indicate omnipotent powers (allowed
-// access to remote object), we need to remove non - present parameters
 void Parser::resolve(ParamElem plst[]) {
 	if (allLength > 0)
 		return;	// ALL has already done this
@@ -642,13 +631,6 @@ bool Parser::endOfTable(ChkElem *addr) {
 	return *x == EOF;
 }
 
-/**
- * Find the verb alternative wanted in a verb list and return
- * the address to it.
- * 
- * @param vrbsadr	Address to start of list
- * @param param		Which parameter to match
- */
 AltElem *Parser::findalt(Aword vrbsadr, Aword param) {
 	VrbElem *vrb;
 	AltElem *alt;
@@ -668,12 +650,6 @@ AltElem *Parser::findalt(Aword vrbsadr, Aword param) {
 	return NULL;
 }
 
-/**
- * Tries a check, returns TRUE if it passed, FALSE otherwise
- * 
- * @param adr	ACODE address to check table
- * @param act	Act if it fails?
- */
 bool Parser::trycheck(Aaddr adr, bool act) {
 	ChkElem *chk = (ChkElem *)addrTo(adr);
 
@@ -694,7 +670,6 @@ bool Parser::trycheck(Aaddr adr, bool act) {
 	}
 }
 
-// Check if current action is possible according to the CHECKs.
 bool Parser::possible() {
 	AltElem *alt[MAXPARAMS + 2];	// List of alt-pointers, one for each param
 	int i;			// Parameter index
@@ -903,7 +878,6 @@ void Parser::tryMatch(ParamElem mlst[]) {
 	plural = anyPlural;		// Remember that we found plural objects
 }
 
-// Find the verb class (not used currently) and 'tryMatch()'
 void Parser::match(ParamElem *mlst) {
 	tryMatch(mlst);			// try to understand what the user said
 
@@ -913,8 +887,6 @@ void Parser::match(ParamElem *mlst) {
 		wrdidx++;			// If so skip the AND
 }
 
-// Execute all activities commanded.Handles possible multiple actions
-// such as THEM or lists of objects.
 void Parser::action(ParamElem plst[]) {
 	int i, mpos;
 	char marker[10];
@@ -977,4 +949,4 @@ void Parser::parse() {
 }
 
 } // End of namespace Alan2
-} // Engine of namespace GLK
+} // End of namespace Glk
diff --git a/engines/glk/alan2/parse.h b/engines/glk/alan2/parse.h
index 4642e74ee0..7198b2d555 100644
--- a/engines/glk/alan2/parse.h
+++ b/engines/glk/alan2/parse.h
@@ -43,35 +43,106 @@ private:
 	char *gettoken(char *tokenBuffer);
 	void agetline();
 	void scan();
+	
+	/**
+	 * Search for a non-verb command
+	 */
 	void nonverb();
+	
 	Abool objhere(Aword obj);
 	Aword acthere(Aword act);
 	Abool isHere(Aword id);
+	
+	/**
+	 * Build a list of objects matching 'all'
+	 */
 	void buildall(ParamElem list[]);
+	
 	void listCopy(ParamElem a[], ParamElem b[]);
 	bool listContains(ParamElem l[], Aword e);
 	void listIntersection(ParamElem a[], ParamElem b[]);
+	
+	/**
+	 * Copy the refs (in dictionary) to a paramList
+	 */
 	void listCopyFromDictionary(ParamElem p[], Aword r[]);
+	
 	int listLength(ParamElem a[]);
+	
+	/**
+	 * Compact a list, i.e remove any NULL elements
+	 */
 	void listCompact(ParamElem a[]);
+	
+	/**
+	 * Merge the paramElems of one list into the first
+	 */
 	void listMerge(ParamElem a[], ParamElem b[]);
+	
+	/**
+	 * Subtract two lists
+	 */
 	void listSubtract(ParamElem a[], ParamElem b[]);
+	
+	/**
+	 * Match an unambigous object reference
+	 */
 	void unambig(ParamElem plst[]);
+	
+	/**
+	 * Match a simple verb command
+	 */
 	void simple(ParamElem olst[]);
+	
+	/**
+	 * Match a complex verb command
+	 */
 	void complex(ParamElem olst[]);
+	
 	bool claCheck(ClaElem *cla);
+	
+	/**
+	 * In case the syntax did not indicate omnipotent powers (allowed
+	 * access to remote object), we need to remove non - present parameters
+	 */
 	void resolve(ParamElem plst[]);
+	
 	bool endOfTable(StxElem *addr);
 	bool endOfTable(ElmElem *addr);
 	bool endOfTable(ClaElem *addr);
 	bool endOfTable(VrbElem *addr);
 	bool endOfTable(AltElem *addr);
 	bool endOfTable(ChkElem *addr);
+	
+	/**
+	 * Find the verb alternative wanted in a verb list and return
+	 * the address to it.
+	 * 
+	 * @param vrbsadr	Address to start of list
+	 * @param param		Which parameter to match
+	 */	
 	AltElem *findalt(Aword vrbsadr, Aword param);
+	
+	/**
+	 * Tries a check, returns TRUE if it passed, FALSE otherwise
+	 * 
+	 * @param adr	ACODE address to check table
+	 * @param act	Act if it fails?
+	 */
 	bool trycheck(Aaddr adr, bool act);
+
+	/**
+	 * Check if current action is possible according to the CHECKs.
+	 */
 	bool possible();
+	
 	void tryMatch(ParamElem mlst[]);
 	void match(ParamElem *mlst);
+	
+	/**
+	 * Execute all activities commanded. Handles possible multiple actions
+	 * such as THEM or lists of objects.
+	 */
 	void action(ParamElem plst[]);
 
 	// TODO: Initialize / move these
@@ -107,6 +178,6 @@ private:
 };
 
 } // End of namespace Alan2
-} // Engine of namespace GLK
+} // End of namespace Glk
 
 #endif