cleanup, add some doxygen docs

svn-id: r8184

2 files changed, 56 insertions, 10 deletions

diff --git a/sky/compact.cpp b/sky/compact.cpp
index d73616d893..f88e71b149 100644
--- a/sky/compact.cpp
+++ b/sky/compact.cpp
@@ -50,6 +50,9 @@
 
 namespace SkyCompact {
 
+/**
+ * Returns the n'th mega set specified by \a megaSet from Compact \a cpt.
+ */
 MegaSet *getMegaSet(Compact *cpt, uint16 megaSet) {
 	switch (megaSet) {
 	case 0:
@@ -65,6 +68,19 @@ MegaSet *getMegaSet(Compact *cpt, uint16 megaSet) {
 	}
 }
 
+/**
+ \brief Returns the turn table for direction \a dir
+ 	from Compact \a cpt in \a megaSet.
+  
+ Functionally equivalent to:
+ \verbatim
+ clear eax
+ mov al,20
+ mul (cpt[esi]).c_dir
+ add ax,(cpt[esi]).c_mega_set
+ lea eax,(cpt[esi+eax]).c_turn_table_up
+ \endverbatim
+*/
 uint16 **getTurnTable(Compact *cpt, uint16 megaSet, uint16 dir) {
 	MegaSet *m = getMegaSet(cpt, megaSet);
 	switch (dir) {
@@ -83,6 +99,21 @@ uint16 **getTurnTable(Compact *cpt, uint16 megaSet, uint16 dir) {
 	}
 }
 
+/**
+ * \brief Returns the script for \a mode from Compact \a cpt.
+ *        Add 2 to \a mode to get the offset.
+ *
+ \verbatim
+ uint16 *scriptNo = SkyCompact::getSub(_compact, mode);
+ uint16 *offset   = SkyCompact::getSub(_compact, mode + 2);
+ uint32 script = (*offset << 16) | *scriptNo;
+ \endverbatim
+ * Is functionally equivalent to:
+ \verbatim
+ mov eax,c_base_sub[ebx+esi]
+ \endverbatim
+ where \a esi is the compact and ebx the mode.
+ */ 
 uint16 *getSub(Compact *cpt, uint16 mode) {
 	switch (mode) {
 	case 0:
@@ -189,6 +220,10 @@ static const uint32 turnTableOffsets[] = {
 	MK32_A5(TurnTable, turnTableTalk),
 };
 
+/**
+ * Returns a void pointer to offset \a off in compact \a cpt
+ * as it would be on a 386.
+ */
 void *getCompactElem(Compact *cpt, uint32 off) {
 	if (off < COMPACT_SIZE)
 		return((uint8 *)cpt + compactOffsets[off]);
diff --git a/sky/logic.cpp b/sky/logic.cpp
index 213c15ea32..b8b6d5e4ab 100644
--- a/sky/logic.cpp
+++ b/sky/logic.cpp
@@ -104,6 +104,11 @@ void SkyLogic::engine() {
 
 void SkyLogic::nop() {}
 
+/**
+ * This function is basicly a wrapper around the real script engine. It runs
+ * the script engine until a script has finished.
+ * @see script()
+ */
 void SkyLogic::logicScript() {
 	// Process the current mega's script
 	// If the script finishes then drop back a level
@@ -113,9 +118,7 @@ void SkyLogic::logicScript() {
 		uint16 *scriptNo = SkyCompact::getSub(_compact, mode);
 		uint16 *offset   = SkyCompact::getSub(_compact, mode + 2);
 
-		uint32 scr = script(*scriptNo, *offset);
-		*scriptNo = (uint16)(scr & 0xffff);
-		*offset   = (uint16)(scr >> 16);
+		*offset = script(*scriptNo, *offset);
 
 		if (!*offset) // script finished
 			_compact->mode -= 4;
@@ -920,15 +923,23 @@ void SkyLogic::initScriptVariables() {
 	memcpy(_scriptVariables + 505, forwardList5b, sizeof(forwardList5b));
 }
 
-uint32 SkyLogic::script(uint16 scriptNo, uint16 offset) {
+/**
+ * \fn uint32 SkyLogic::script(uint16 scriptNo, uint16 offset)
+ * \brief This is the actual script engine. 
+ *        It interprets script \a scriptNo starting at \a offset
+ *
+ * \param scriptNo The script to interpret.
+ * 	\li \arg Bits 0-11 - Script number
+ * 	\li \arg Bits 12-15 - Module number
+ * \param offset At which offset to start interpreting the script.
+ *
+ * @return 0 if script finished. Else offset where to continue.
+ */
+uint16 SkyLogic::script(uint16 scriptNo, uint16 offset) {
 script:
 	// process a script
 	// low level interface to interpreter
 
-	// scriptNo:
-	// Bit  0-11 - Script number
-	// Bit 12-15 - Module number
-
 	uint16 moduleNo = (uint16)((scriptNo & 0xff00) >> 12);
 	debug(3, "Doing Script %x\n", (offset << 16) | scriptNo);
 	uint16 *scriptData = _moduleList[moduleNo]; // get module address
@@ -1039,7 +1050,7 @@ script:
 				_compact = saveCpt;
 
 				if (!ret)
-					return (((scriptData - moduleStart) << 16) | scriptNo);
+					return (scriptData - moduleStart);
 			}
 			break;
 		case 12: // more_than
@@ -1092,7 +1103,7 @@ script:
 			}
 		case 13:
 		case 19: // script_exit
-			return scriptNo;
+			return 0;
 		case 20: // restart_script
 			goto script;
 		default: