2 files changed, 60 insertions, 34 deletions

diff --git a/engines/gob/script.cpp b/engines/gob/script.cpp
index 2f6c2b2098..ab2d8cdaf2 100644
--- a/engines/gob/script.cpp
+++ b/engines/gob/script.cpp
@@ -40,10 +40,8 @@ Script::Script(GobEngine *vm) : _vm(vm) {
 	_finished = true;
 
 	_totData = 0;
-
-	_totSize = 0;
-
 	_totPtr = 0;
+	_totSize = 0;
 
 	_lomHandle = -1;
 }
@@ -63,7 +61,7 @@ uint32 Script::read(byte *data, uint32 size) {
 	return toRead;
 }
 
-uint32 Script::peek(byte *data, uint32 size, int32 offset) {
+uint32 Script::peek(byte *data, uint32 size, int32 offset) const {
 	int32 totOffset = ((_totPtr + offset) - _totData);
 
 	if (totOffset < 0)
@@ -104,6 +102,7 @@ bool Script::seek(int32 offset, int whence) {
 	if ((offset < 0) || (((uint32) offset) >= _totSize))
 		return false;
 
+	// A successful seek means the script file continues to be executed
 	_finished = false;
 
 	_totPtr = _totData + offset;
@@ -306,13 +305,17 @@ bool Script::load(const char *fileName) {
 
 	const char *dot;
 	if ((dot = strrchr(fileName, '.'))) {
+		// fileName includes an extension
+
 		fileBase = new Common::String(fileName, dot);
 
+		// Is it a LOM file?
 		if (!scumm_stricmp(dot + 1, "LOM"))
 			lom = true;
 	} else
 		fileBase = new Common::String(fileName);
 
+	// If it's a LOM file, it includes the TOT file
 	_totFile = *fileBase + (lom ? ".lom" : ".tot");
 
 	delete fileBase;
@@ -334,9 +337,14 @@ bool Script::load(const char *fileName) {
 
 bool Script::loadTOT(const Common::String &fileName) {
 	if (_vm->_dataIO->existData(fileName.c_str())) {
+		// Direct data file
+
 		_totSize = _vm->_dataIO->getDataSize(_totFile.c_str());
 		_totData = _vm->_dataIO->getData(_totFile.c_str());
+
 	} else  {
+		// Trying to read the TOT file out of the currently loaded video file
+
 		Common::MemoryReadStream *videoExtraData = _vm->_vidPlayer->getExtraData(fileName.c_str());
 
 		if (videoExtraData) {
@@ -383,6 +391,7 @@ void Script::unloadTOT() {
 	if (_lomHandle >= 0)
 		_vm->_dataIO->closeData(_lomHandle);
 
+	// Unwind the call stack
 	while (!_callStack.empty())
 		pop();
 
diff --git a/engines/gob/script.h b/engines/gob/script.h
index 8f1352de86..28d8483272 100644
--- a/engines/gob/script.h
+++ b/engines/gob/script.h
@@ -39,61 +39,78 @@ public:
 	Script(GobEngine *vm);
 	~Script();
 
+	/** Read data and move the pointer accordingly. */
 	uint32 read(byte *data, uint32 size);
-	uint32 peek(byte *data, uint32 size, int32 offset = 0);
+	/** Read data (from an optional offset) without moving the pointer. */
+	uint32 peek(byte *data, uint32 size, int32 offset = 0) const;
 
-	byte   readByte();
-	char   readChar();
-	uint8  readUint8();
-	uint16 readUint16();
-	uint32 readUint32();
-	int8   readInt8();
-	int16  readInt16();
-	int32  readInt32();
+	// Stream properties
+	int32 pos() const;
+	int32 getSize() const;
 
-	char *readString(int32 length = -1);
+	// Stream seeking
+	bool seek(int32 offset, int whence = SEEK_SET);
+	bool skip(uint32 offset);
 
-	byte   peekByte(int32 offset = 0);
-	char   peekChar(int32 offset = 0);
-	uint8  peekUint8(int32 offset = 0);
+	// Reading data
+	byte   readByte  ();
+	char   readChar  ();
+	uint8  readUint8 ();
+	uint16 readUint16();
+	uint32 readUint32();
+	int8   readInt8  ();
+	int16  readInt16 ();
+	int32  readInt32 ();
+	char  *readString(int32 length = -1);
+
+	// Peeking data
+	byte   peekByte  (int32 offset = 0);
+	char   peekChar  (int32 offset = 0);
+	uint8  peekUint8 (int32 offset = 0);
 	uint16 peekUint16(int32 offset = 0);
 	uint32 peekUint32(int32 offset = 0);
-	int8   peekInt8(int32 offset = 0);
-	int16  peekInt16(int32 offset = 0);
-	int32  peekInt32(int32 offset = 0);
-
-	char *peekString(int32 offset = 0);
+	int8   peekInt8  (int32 offset = 0);
+	int16  peekInt16 (int32 offset = 0);
+	int32  peekInt32 (int32 offset = 0);
+	char  *peekString(int32 offset = 0);
 
+	// Expression parsing functions
 	int16 readVarIndex(uint16 *size = 0, uint16 *type = 0);
 	int16 readValExpr(byte stopToken = 99);
 	int16 readExpr(byte stopToken, byte *type);
-	void skipExpr(char stopToken);
+	void  skipExpr(char stopToken);
 
+	// Higher-level expression parsing functions
 	char evalExpr(int16 *pRes);
 	bool evalBoolResult();
 
+	// Accessing the result of expressions
 	int32 getResultInt();
 	char *getResultStr();
 
-	int32 pos() const;
-	int32 getSize() const;
-	bool seek(int32 offset, int whence = SEEK_SET);
-	bool skip(uint32 offset);
-
+	/** Returns the offset the specified pointer is within the script data. */
 	uint32 getOffset(byte *ptr);
+	/** Returns the raw data pointer. */
 	byte *getData();
 
+	/** Load a script file. */
 	bool load(const char *fileName);
-
+	/** Unload the script. */
 	void unload();
-
+	/** Was a script loaded? */
 	bool isLoaded() const;
 
+	/** Setting the 'finished' property. */
 	void setFinished(bool finished);
+	/** Querying the 'finished' property. */
 	bool isFinished() const;
 
+	// Call stack operations
+	/** Push the current script position onto the call stack. */
 	void push();
+	/** Pop a script position from the call stack (and return there). */
 	void pop(bool ret = true);
+	/** Push the current script position and branch to the specified offset. */
 	void call(uint32 offset);
 
 private:
@@ -108,20 +125,20 @@ private:
 	bool _finished;
 
 	Common::String _totFile;
-
 	byte *_totData;
-
-	uint32 _totSize;
-
 	byte *_totPtr;
+	uint32 _totSize;
 
 	int16 _lomHandle;
 
 	Common::Stack<CallEntry> _callStack;
 
+	/** Loading a TOT file. */
 	bool loadTOT(const Common::String &fileName);
+	/** Loading a LOM file. */
 	bool loadLOM(const Common::String &fileName);
 
+	/** Unloading a TOT file. */
 	void unloadTOT();
 };