Commented on loop() before refactoring.

svn-id: r45604

3 files changed, 23 insertions, 3 deletions

diff --git a/engines/draci/animation.h b/engines/draci/animation.h
index 11cdc3d414..e7ffc9d761 100644
--- a/engines/draci/animation.h
+++ b/engines/draci/animation.h
@@ -104,8 +104,11 @@ public:
 
 	void markDirtyRect(Surface *surface) const;
 
-	// Animation callbacks
-
+	// Animation callbacks.  They can only do simple things, such as
+	// setting the value of some variable or stopping an animation.  In
+	// particular, they cannot run sub-loops or anything like that, because
+	// the callback is called at an arbitrary time without much control
+	// over what the state of the rest of the program is.
 	void registerCallback(AnimationCallback callback) { _callback = callback; }
 
 	void doNothing() {}
diff --git a/engines/draci/game.cpp b/engines/draci/game.cpp
index a38d96f1db..d8f9f899c0 100644
--- a/engines/draci/game.cpp
+++ b/engines/draci/game.cpp
@@ -164,6 +164,7 @@ void Game::start() {
 			continue;
 		}
 
+		// Call the outer loop doing all the hard job.
 		loop();
 	}
 }
@@ -240,6 +241,11 @@ void Game::init() {
 }
 
 void Game::loop() {
+	// Can run both as an outer and inner loop.  In both mode it updates
+	// the screen according to the timer.  It the outer mode it also reacts
+	// to user events.  In the inner mode, the loop runs until its stopping
+	// condition, possibly stopping earlier if the user interrupts it,
+	// however no other user intervention is allowed.
 	Surface *surface = _vm->_screen->getSurface();
 
 	do {
@@ -838,6 +844,8 @@ int Game::dialogueDraw() {
 	_oldObjUnderCursor = kObjectNotFound;
 
 	if (_dialogueLinesNum > 1) {
+		// Call the game loop to enable interactivity until the user
+		// selects his choice.
 		_vm->_mouse->cursorOn();
 		setExitLoop(false);
 		loop();
diff --git a/engines/draci/script.cpp b/engines/draci/script.cpp
index f7ec7578fb..f938737728 100644
--- a/engines/draci/script.cpp
+++ b/engines/draci/script.cpp
@@ -357,6 +357,8 @@ void Script::play(Common::Queue<int> &params) {
 		return;
 	}
 
+	// Runs just one phase of the loop and exits.  Used when waiting for a
+	// particular animation phase to come.
 	_vm->_game->setLoopSubstatus(kSubstatusStrange);
 	_vm->_game->setExitLoop(true);
 	_vm->_game->loop();
@@ -469,6 +471,7 @@ void Script::startPlay(Common::Queue<int> &params) {
 		_vm->_anims->play(animID);
 	}
 
+	// Runs an inner loop until the animation ends.
 	_vm->_game->loop();
 	_vm->_game->setExitLoop(false);
 	_vm->_anims->stop(animID);
@@ -675,6 +678,7 @@ void Script::walkOnPlay(Common::Queue<int> &params) {
 	SightDirection dir = static_cast<SightDirection> (params.pop());
 
 	// HACK: This should be an onDest action when hero walking is properly implemented
+	// For now, we just go throught the loop-body once to redraw the screen.
 	_vm->_game->setExitLoop(true);
 
 	_vm->_game->walkHero(x, y, dir);
@@ -776,7 +780,7 @@ void Script::talk(Common::Queue<int> &params) {
 	// "exit immediately" state
 	_vm->_game->setExitLoop(false);
 
-	// Call the game loop to enable interactivity until the text expires
+	// Call the game loop to enable interactivity until the text expires.
 	_vm->_game->loop();
 
 	// Delete the text
@@ -871,6 +875,10 @@ void Script::fadePalette(Common::Queue<int> &params) {
 	params.pop();	// unused first and last
 	params.pop();
 	int phases = params.pop();
+
+	// Let the palette fade in the background while the game continues.
+	// Since we don't set substatus to kSubstatusFade, the outer loop will
+	// just continue rather than exit.
 	_vm->_game->initializeFading(phases);
 }
 
@@ -880,6 +888,7 @@ void Script::fadePalettePlay(Common::Queue<int> &params) {
 	int phases = params.pop();
 	_vm->_game->initializeFading(phases);
 
+	// Call the game loop to enable interactivity until the fading is done.
 	_vm->_game->setLoopSubstatus(kSubstatusFade);
 	_vm->_game->loop();
 	_vm->_game->setExitLoop(false);