AVALANCHE: Use Doxygen comments in Dialogs, set private some members

2 files changed, 86 insertions, 41 deletions

diff --git a/engines/avalanche/dialogs.cpp b/engines/avalanche/dialogs.cpp
index f3b2688600..fd2e47b34d 100644
--- a/engines/avalanche/dialogs.cpp
+++ b/engines/avalanche/dialogs.cpp
@@ -48,7 +48,11 @@ void Dialogs::init() {
 	resetScrollDriver();
 }
 
-void Dialogs::setReadyLight(byte state) {     // Sets "Ready" light to whatever
+/**
+ * Determine the color of the ready light and draw it
+ * @remarks	Originally called 'state'
+ */
+void Dialogs::setReadyLight(byte state) {
 	if (_vm->_ledStatus == state)
 		return; // Already like that!
 
@@ -63,7 +67,7 @@ void Dialogs::setReadyLight(byte state) {     // Sets "Ready" light to whatever
 		color = kColorGreen;
 		break; // Hit a key
 	}
-	warning("STUB: Scrolls::state()");
+	warning("STUB: Dialogs::setReadyLight()");
 
 	CursorMan.showMouse(false);
 	_vm->_graphics->drawReadyLight(color);
@@ -104,6 +108,10 @@ void Dialogs::say(int16 x, int16 y, Common::String z) {
 	}
 }
 
+/**
+ * One of the 3 "Mode" functions passed as ScrollsFunctionType parameters.
+ * @remarks	Originally called 'normscroll'
+ */
 void Dialogs::scrollModeNormal() {
 	// Original code is:
 	// egg : array[1..8] of char = ^P^L^U^G^H+'***';
@@ -124,11 +132,10 @@ void Dialogs::scrollModeNormal() {
 		_vm->_graphics->refreshScreen();
 
 		_vm->getEvent(event);
-		if (_vm->shouldQuit() || 
-			(event.type == Common::EVENT_LBUTTONUP) ||
-			((event.type == Common::EVENT_KEYDOWN) && ((event.kbd.keycode == Common::KEYCODE_ESCAPE)
-			|| (event.kbd.keycode == Common::KEYCODE_RETURN) || (event.kbd.keycode == Common::KEYCODE_HASH)
-			|| (event.kbd.keycode == Common::KEYCODE_PLUS))))
+		if ((event.type == Common::EVENT_LBUTTONUP) ||
+			((event.type == Common::EVENT_KEYDOWN) && ((event.kbd.keycode == Common::KEYCODE_ESCAPE) ||
+			(event.kbd.keycode == Common::KEYCODE_RETURN) || (event.kbd.keycode == Common::KEYCODE_HASH) ||
+			(event.kbd.keycode == Common::KEYCODE_PLUS))))
 			break;
 	}
 
@@ -176,6 +183,11 @@ void Dialogs::scrollModeNormal() {
 	warning("STUB: Scrolls::scrollModeNormal()");
 }
 
+/**
+ * One of the 3 "Mode" functions passed as ScrollsFunctionType parameters.
+ * The "asking" scroll. Used indirectly in diplayQuestion().
+ * @remarks	Originally called 'dialogue'
+ */
 void Dialogs::scrollModeDialogue() {
 	_vm->_graphics->loadMouse(kCurHand);
 
@@ -232,6 +244,11 @@ bool Dialogs::theyMatch(TuneType &played) {
 	return mistakes < 5;
 }
 
+/**
+ * One of the 3 "Mode" functions passed as ScrollsFunctionType parameters.
+ * Part of the harp mini-game.
+ * @remarks	Originally called 'music_Scroll'
+ */
 void Dialogs::scrollModeMusic() {
 	setReadyLight(3);
 	_vm->_seeScroll = true;
@@ -347,16 +364,29 @@ void Dialogs::resetScrollDriver() {
 	_vm->_interrogation = 0; // Always reset after a scroll comes up.
 }
 
-void Dialogs::ringBell() {   // Pussy's in the well. Who put her in? Little...
+/**
+ * Rings the bell x times
+ * @remarks	Originally called 'dingdongbell'
+ */
+void Dialogs::ringBell() {
 	for (int i = 0; i < _scrollBells; i++)
-		_vm->errorLed(); // Ring the bell "x" times.
+		_vm->errorLed(); // Ring the bell "_scrollBells" times.
 }
 
+/**
+ * This moves the mouse pointer off the scroll so that you can read it.
+ * @remarks	Originally called 'dodgem'
+ */
 void Dialogs::dodgem() {
 	_dodgeCoord = _vm->getMousePos();
 	g_system->warpMouse(_dodgeCoord.x, _underScroll); // Move the pointer off the scroll.
 }
 
+/**
+ * This is the opposite of Dodgem.
+ * It moves the mouse pointer back, IF you haven't moved it in the meantime.
+ * @remarks	Originally called 'undodgem'
+ */
 void Dialogs::unDodgem() {
 	Common::Point actCoord = _vm->getMousePos();
 	if ((actCoord.x == _dodgeCoord.x) && (actCoord.y == _underScroll))
@@ -512,6 +542,10 @@ void Dialogs::reset() {
 	}
 }
 
+/**
+ * Natural state of bubbles
+ * @remarks	Originally called 'natural'
+ */
 void Dialogs::setBubbleStateNatural() {
 	_vm->_talkX = 320;
 	_vm->_talkY = 200;
@@ -540,11 +574,18 @@ Common::String Dialogs::displayMoney() {
 	return result;
 }
 
+/**
+ * Strip trailing character in a string
+ * @remarks	Originally called 'strip'
+ */
 void Dialogs::stripTrailingSpaces(Common::String &str) {
-	while (str[str.size() - 1] == ' ')
+	while (str.lastChar() == ' ')
 		str.deleteLastChar();
 }
 
+/**
+ * Does the word wrapping.
+ */
 void Dialogs::solidify(byte n) {
 	if (!_scroll[n].contains(' '))
 		return; // No spaces.
@@ -558,6 +599,9 @@ void Dialogs::solidify(byte n) {
 	stripTrailingSpaces(_scroll[n]);
 }
 
+/**
+ * @remarks	Originally called 'calldriver'
+ */
 void Dialogs::callDialogDriver() {
 //	bool was_virtual; // Was the mouse cursor virtual on entry to this proc?
 	warning("STUB: Scrolls::calldrivers()");
@@ -737,6 +781,10 @@ void Dialogs::callDialogDriver() {
 	}
 }
 
+/**
+ * Display text by calling the dialog driver
+ * @remarks	Originally called 'display'
+ */
 void Dialogs::displayText(Common::String text) { // TODO: REPLACE BUFFER WITH A STRING!!!!!!!!!!
 	_bufSize = text.size();
 	memcpy(_buffer, text.c_str(), _bufSize);
@@ -784,6 +832,10 @@ void Dialogs::loadFont() {
 	file.close();
 }
 
+/**
+ * Practically this one is a mini-game which called when you play the harp in the monastery.
+ * @remarks	Originally called 'musical_scroll'
+ */
 void Dialogs::displayMusicalScroll() {
 	Common::String tmpStr = Common::String::format("To play the harp...%c%cUse these keys:%c%cQ W E R T Y U I O P [ ]%c%cOr press Enter to stop playing.%c", 
 		        kControlNewLine, kControlNewLine, kControlNewLine, kControlInsertSpaces, kControlNewLine, kControlNewLine, kControlToBuffer);
@@ -796,8 +848,6 @@ void Dialogs::displayMusicalScroll() {
 	reset();
 }
 
-// From Visa:
-
 void Dialogs::unSkrimble() {
 	for (uint16  i = 0; i < _bufSize; i++)
 		_buffer[i] = (~(_buffer[i] - (i + 1))) % 256;
@@ -1035,6 +1085,10 @@ void Dialogs::talkTo(byte whom) {
 	}
 }
 
+/**
+ * This makes Avalot say the response.
+ * @remarks	Originally called 'sayit'
+ */
 void Dialogs::sayIt(Common::String str) {
 	Common::String x = str;
 	x.setChar(toupper(x[0]), 0);
diff --git a/engines/avalanche/dialogs.h b/engines/avalanche/dialogs.h
index 94ffaf9401..d8c205ac90 100644
--- a/engines/avalanche/dialogs.h
+++ b/engines/avalanche/dialogs.h
@@ -41,28 +41,21 @@ typedef void (Dialogs::*DialogFunctionType)();
 
 class Dialogs {
 public:
-	bool _aboutBox; // Is this the about box?
+	bool _aboutBox; // Is this the about box? - Used in scrollModeNormal(), not yet fully implemented
 	FontType _fonts[2];
 
 	Dialogs(AvalancheEngine *vm);
 
 	void init();
-	void setReadyLight(byte state); // Sets "Ready" light to whatever.
-	void drawScroll(DialogFunctionType modeFunc);
-	void drawBubble(DialogFunctionType modeFunc);
 	void reset();
-	void callDialogDriver();
+	void setReadyLight(byte state);
 	void displayText(Common::String text);
 	bool displayQuestion(Common::String question);
-	void setBubbleStateNatural(); // Natural state of bubbles
-	Common::String displayMoney();
-	void displayMusicalScroll(); // Practically this one is a mini-game which called when you play the harp in the monastery.
-
-	// From Visa:
+	void setBubbleStateNatural();
+	void displayMusicalScroll();
 	void displayScrollChain(char block, byte point, bool report = true, bool bubbling = false);
 	void talkTo(byte whom);
-
-	void sayIt(Common::String str);  // This makes Avalot say the response.
+	void sayIt(Common::String str);
 
 private:
 	AvalancheEngine *_vm;
@@ -72,46 +65,44 @@ private:
 		kFontStyleItalic
 	};
 
-	static const int16 kHalfIconWidth = 19; // Half the width of an icon.
+	static const int16 kHalfIconWidth = 19;
 
-	int16 _shadowBoxX, _shadowBoxY;
-	byte _currentFont; // Current font
 	Common::String _scroll[15];
 	Common::Point _dodgeCoord;
-	byte _param; // For using arguments code
-	byte _useIcon;
 	byte _maxLineNum;
 	bool _scReturn;
+	bool _noError;
+	byte _currentFont;
+	byte _param; // For using arguments code
+	byte _useIcon;
 	byte _scrollBells; // no. of times to ring the bell
 	byte _buffer[2000];
 	uint16 _bufSize;
 	int16 _underScroll; // Y-coord of just under the scroll text.
+	int16 _shadowBoxX, _shadowBoxY;
 
-	// These 3 "Mode" functions are always passed as ScrollsFunctionType parameters.
+	void callDialogDriver();
+	void drawBubble(DialogFunctionType modeFunc);
+	void drawScroll(DialogFunctionType modeFunc);
 	void scrollModeNormal();
-	// The "asking" scroll. Used indirectly in diplayQuestion().
 	void scrollModeDialogue();
-	// Part of the harp mini-game.
 	void scrollModeMusic();
 
 	// These 2 are used only in musicalScroll().
 	void store(byte what, TuneType &played);
 	bool theyMatch(TuneType &played);
+	void stripTrailingSpaces(Common::String &str);
+	void solidify(byte n);
+	void dodgem();
+	void unDodgem();
 
-	void stripTrailingSpaces(Common::String &str); // Original: strip.
-	void solidify(byte n); // Does the word wrapping.
-
-	void dodgem(); // This moves the mouse pointer off the scroll so that you can read it.
-	void unDodgem(); // This is the opposite of Dodgem. It moves the mouse pointer back, IF you haven't moved it in the meantime.
-
+	Common::String displayMoney();
 	void easterEgg();
 	void say(int16 x, int16 y, Common::String text);
 	void resetScrollDriver();
-	void ringBell(); // Original: dingdongbell
+	void ringBell();
 	void loadFont();
 
-	// From Visa:
-	bool _noError;
 	void unSkrimble();
 	void doTheBubble();
 	void speak(byte who, byte subject);