SHERLOCK: Extra method comments

14 files changed, 132 insertions, 17 deletions

diff --git a/engines/sherlock/animation.cpp b/engines/sherlock/animation.cpp
index 1d84a30c0f..aea4793a76 100644
--- a/engines/sherlock/animation.cpp
+++ b/engines/sherlock/animation.cpp
@@ -64,6 +64,9 @@ static const int NO_FRAMES = FRAMES_END;
 Animation::Animation(SherlockEngine *vm): _vm(vm) {
 }
 
+/**
+ * Play a full-screen animation
+ */
 bool Animation::play(const Common::String &filename, int minDelay, int fade, 
 		bool setPalette, int speed) {
 	Events &events = *_vm->_events;
diff --git a/engines/sherlock/debugger.cpp b/engines/sherlock/debugger.cpp
index b8ac8bef6a..b3dac71d5e 100644
--- a/engines/sherlock/debugger.cpp
+++ b/engines/sherlock/debugger.cpp
@@ -30,6 +30,9 @@ Debugger::Debugger(SherlockEngine *vm) : GUI::Debugger(), _vm(vm) {
 	registerCmd("scene", WRAP_METHOD(Debugger, cmd_scene));
 }
 
+/**
+ * Converts a decimal or hexadecimal string into a number
+ */
 static int strToInt(const char *s) {
 	if (!*s)
 		// No string at all
@@ -46,6 +49,9 @@ static int strToInt(const char *s) {
 	return (int)tmp;
 }
 
+/**
+ * Switch to another scene
+ */
 bool Debugger::cmd_scene(int argc, const char **argv) {
 	if (argc != 2) {
 		debugPrintf("Format: scene <room>\n");
diff --git a/engines/sherlock/detection.cpp b/engines/sherlock/detection.cpp
index c4d1c65fd5..14fc04cc73 100644
--- a/engines/sherlock/detection.cpp
+++ b/engines/sherlock/detection.cpp
@@ -36,14 +36,23 @@ struct SherlockGameDescription {
 	uint32 features;
 };
 
+/**
+ * Returns the Id of the game
+ */
 uint32 SherlockEngine::getGameID() const {
 	return _gameDescription->gameID;
 }
 
+/**
+ * Returns the features the currently playing game has
+ */
 uint32 SherlockEngine::getGameFeatures() const {
 	return _gameDescription->features;
 }
 
+/**
+ * Return's the platform the game's datafiles are for
+ */
 Common::Platform SherlockEngine::getPlatform() const {
 	return _gameDescription->desc.platform;
 }
@@ -79,6 +88,9 @@ public:
 	SaveStateDescriptor querySaveMetaInfos(const char *target, int slot) const;
 };
 
+/**
+ * Creates an instance of the game engine
+ */
 bool SherlockMetaEngine::createInstance(OSystem *syst, Engine **engine, const ADGameDescription *desc) const {
 	const Sherlock::SherlockGameDescription *gd = (const Sherlock::SherlockGameDescription *)desc;
 	if (gd) {
@@ -97,6 +109,9 @@ bool SherlockMetaEngine::createInstance(OSystem *syst, Engine **engine, const AD
 	return gd != 0;
 }
 
+/**
+ * Returns a list of features the game's MetaEngine support
+ */
 bool SherlockMetaEngine::hasFeature(MetaEngineFeature f) const {
 	return
 		(f == kSupportsListSaves) ||
@@ -106,6 +121,9 @@ bool SherlockMetaEngine::hasFeature(MetaEngineFeature f) const {
 		(f == kSavesSupportThumbnail);
 }
 
+/**
+ * Returns a list of features the game itself supports
+ */
 bool Sherlock::SherlockEngine::hasFeature(EngineFeature f) const {
 	return
 		(f == kSupportsRTL) ||
@@ -113,19 +131,31 @@ bool Sherlock::SherlockEngine::hasFeature(EngineFeature f) const {
 		(f == kSupportsSavingDuringRuntime);
 }
 
+/**
+ * Return a list of savegames
+ */
 SaveStateList SherlockMetaEngine::listSaves(const char *target) const {
 	return Sherlock::SaveManager(nullptr, "").getSavegameList(target);
 }
 
+/**
+ * Returns the maximum number of allowed save slots
+ */
 int SherlockMetaEngine::getMaximumSaveSlot() const {
 	return MAX_SAVEGAME_SLOTS;
 }
 
+/**
+ * Deletes a savegame in the specified slot
+ */
 void SherlockMetaEngine::removeSaveState(const char *target, int slot) const {	
 	Common::String filename = Sherlock::SaveManager(nullptr, target).generateSaveName(slot);
 	g_system->getSavefileManager()->removeSavefile(filename);
 }
 
+/**
+ * Given a specified savegame slot, returns extended information for the save 
+ */
 SaveStateDescriptor SherlockMetaEngine::querySaveMetaInfos(const char *target, int slot) const {
 	Common::String filename = Sherlock::SaveManager(nullptr, target).generateSaveName(slot);
 	Common::InSaveFile *f = g_system->getSavefileManager()->openForLoading(filename);
diff --git a/engines/sherlock/events.cpp b/engines/sherlock/events.cpp
index f7cbdd301e..a4fc93edd9 100644
--- a/engines/sherlock/events.cpp
+++ b/engines/sherlock/events.cpp
@@ -208,7 +208,6 @@ Common::KeyState Events::getKey() {
 	return keyState;
 }
 
-
 /**
  * Clear any current keypress or mouse click
  */
@@ -227,7 +226,6 @@ void Events::clearKeyboard() {
 	_pendingKeys.clear();
 }
 
-
 /**
  * Delay for a given number of game frames, where each frame is 1/60th of a second
  */
@@ -236,6 +234,9 @@ void Events::wait(int numFrames) {
 	delay(totalMilli);
 }
 
+/**
+ * Does a delay of the specified number of milliseconds
+ */
 bool Events::delay(uint32 time, bool interruptable) {
 	// Different handling for really short versus extended times
 	if (time < 10) {
diff --git a/engines/sherlock/graphics.cpp b/engines/sherlock/graphics.cpp
index 6fd046e458..2095e7d35d 100644
--- a/engines/sherlock/graphics.cpp
+++ b/engines/sherlock/graphics.cpp
@@ -47,6 +47,10 @@ Surface::~Surface() {
 		free();
 }
 
+/**
+ * Sets up an internal surface with the specified dimensions that will be automatically freed
+ * when the surface object is destroyed
+ */
 void Surface::create(uint16 width, uint16 height) {
 	if (_freePixels)
 		free();
@@ -55,7 +59,6 @@ void Surface::create(uint16 width, uint16 height) {
 	_freePixels = true;
 }
 
-
 /**
  * Copy a surface into this one
  */
@@ -159,6 +162,9 @@ void Surface::fillRect(int x1, int y1, int x2, int y2, byte color) {
 	fillRect(Common::Rect(x1, y1, x2, y2), color);
 }
 
+/**
+ * Fill a given area of the surface with a given color
+ */
 void Surface::fillRect(const Common::Rect &r, byte color) {
     Graphics::Surface::fillRect(r, color);
 	addDirtyRect(r);
@@ -196,5 +202,4 @@ bool Surface::clip(Common::Rect &srcBounds, Common::Rect &destBounds) {
 	return true;
 }
 
-
 } // End of namespace Sherlock
diff --git a/engines/sherlock/inventory.cpp b/engines/sherlock/inventory.cpp
index 798531ea14..935a306619 100644
--- a/engines/sherlock/inventory.cpp
+++ b/engines/sherlock/inventory.cpp
@@ -358,6 +358,9 @@ void Inventory::highlight(int index, byte color) {
 	screen.slamArea(8 + slot * 52, 165, 44, 30);
 }
 
+/**
+ * Support method for updating the screen
+ */
 void Inventory::doInvJF() {
 	Screen &screen = *_vm->_screen;
 	Talk &talk = *_vm->_talk;
diff --git a/engines/sherlock/journal.cpp b/engines/sherlock/journal.cpp
index 67cff15218..25b0bb5451 100644
--- a/engines/sherlock/journal.cpp
+++ b/engines/sherlock/journal.cpp
@@ -91,6 +91,9 @@ void Journal::record(int converseNum, int statementNum, bool replyOnly) {
 	}
 }
 
+/**
+ * Load the list of location names that the journal will make reference to
+ */
 void Journal::loadJournalLocations() {
 	Resources &res = *_vm->_res;
 	char c;
diff --git a/engines/sherlock/objects.cpp b/engines/sherlock/objects.cpp
index ff8f6393db..fa5dfee26c 100644
--- a/engines/sherlock/objects.cpp
+++ b/engines/sherlock/objects.cpp
@@ -361,6 +361,9 @@ void Sprite::checkSprite() {
 
 /*----------------------------------------------------------------*/
 
+/**
+ * Synchronize the data for a savegame 
+ */
 void ActionType::synchronize(Common::SeekableReadStream &s) {
 	char buffer[12];
 	
@@ -384,6 +387,9 @@ UseType::UseType() {
 	_lFlag[0] = _lFlag[1] = 0;
 }
 
+/**
+ * Synchronize the data for a savegame 
+ */
 void UseType::synchronize(Common::SeekableReadStream &s) {
 	char buffer[12];
 
@@ -816,11 +822,11 @@ void Object::setObjSequence(int seq, bool wait) {
 }
 
 /**
-* Checks for codes
-* @param name		The name to check for codes
-* @param messages	Provides a lookup list of messages that can be printed
-* @returns		0 if no codes are found, 1 if codes were found
-*/
+ * Checks for codes
+ * @param name		The name to check for codes
+ * @param messages	Provides a lookup list of messages that can be printed
+ * @returns		0 if no codes are found, 1 if codes were found
+ */
 int Object::checkNameForCodes(const Common::String &name, const char *const messages[]) {
 	Map &map = *_vm->_map;
 	People &people = *_vm->_people;
@@ -1090,6 +1096,9 @@ const Common::Rect Object::getOldBounds() const {
 
 /*----------------------------------------------------------------*/
 
+/**
+ * Synchronize the data for a savegame 
+ */
 void CAnim::synchronize(Common::SeekableReadStream &s) {
 	char buffer[12];
 	s.read(buffer, 12);
diff --git a/engines/sherlock/people.cpp b/engines/sherlock/people.cpp
index ed6e0607bd..5c4014f1a2 100644
--- a/engines/sherlock/people.cpp
+++ b/engines/sherlock/people.cpp
@@ -217,6 +217,9 @@ People::~People() {
 	delete[] _portrait._sequences;
 }
 
+/**
+ * Reset the player data
+ */
 void People::reset() {
 	Sprite &p = _data[PLAYER];
 
@@ -239,6 +242,9 @@ void People::reset() {
 	p._status = 0;
 }
 
+/**
+ * Load the walking images for Sherlock
+ */
 bool People::loadWalk() {
 	if (_walkLoaded) {
 		return false;
@@ -267,10 +273,10 @@ bool People::freeWalk() {
 }
 
 /**
-* Set the variables for moving a character from one poisition to another
-* in a straight line - goAllTheWay must have been previously called to
-* check for any obstacles in the path.
-*/
+ * Set the variables for moving a character from one poisition to another
+ * in a straight line - goAllTheWay must have been previously called to
+ * check for any obstacles in the path.
+ */
 void People::setWalking() {
 	Map &map = *_vm->_map;
 	Scene &scene = *_vm->_scene;
diff --git a/engines/sherlock/scene.cpp b/engines/sherlock/scene.cpp
index 497a8d551c..c714574e08 100644
--- a/engines/sherlock/scene.cpp
+++ b/engines/sherlock/scene.cpp
@@ -559,7 +559,7 @@ void Scene::checkSceneFlags(bool flag) {
  */
 void Scene::checkInventory() {
 	for (uint shapeIdx = 0; shapeIdx < _bgShapes.size(); ++shapeIdx) {
-		for (uint invIdx = 0; invIdx < _vm->_inventory->_holdings; ++invIdx) {
+		for (int invIdx = 0; invIdx < _vm->_inventory->_holdings; ++invIdx) {
 			if (scumm_stricmp(_bgShapes[shapeIdx]._name.c_str(),
 				(*_vm->_inventory)[invIdx]._name.c_str()) == 0) {
 				_bgShapes[shapeIdx]._type = INVALID;
@@ -802,6 +802,9 @@ void Scene::updateBackground() {
 	screen.resetDisplayBounds();
 }
 
+/**
+ * Check whether the passed area intersects with one of the scene's exits
+ */
 Exit *Scene::checkForExit(const Common::Rect &r) {
 	for (uint idx = 0; idx < _exits.size(); ++idx) {
 		if (_exits[idx]._bounds.intersects(r))
diff --git a/engines/sherlock/screen.cpp b/engines/sherlock/screen.cpp
index 01d3b9155a..97b23e7c8e 100644
--- a/engines/sherlock/screen.cpp
+++ b/engines/sherlock/screen.cpp
@@ -50,6 +50,9 @@ Screen::~Screen() {
 	delete _font;
 }
 
+/**
+ * Set the font to use for writing text on the screen
+ */
 void Screen::setFont(int fontNumber) {
 	_fontNumber = fontNumber;
 	Common::String fname = Common::String::format("FONT%d.VGS", fontNumber + 1);
@@ -64,6 +67,9 @@ void Screen::setFont(int fontNumber) {
 		_fontHeight = MAX((uint16)_fontHeight, (*_font)[idx]._frame.h);
 }
 
+/**
+ * Handles updating any dirty areas of the screen Surface object to the physical screen
+ */
 void Screen::update() {
 	// Merge the dirty rects
 	mergeDirtyRects();
@@ -82,14 +88,23 @@ void Screen::update() {
 	_dirtyRects.clear();
 }
 
+/**
+ * Return the currently active palette
+ */
 void Screen::getPalette(byte palette[PALETTE_SIZE]) {
 	g_system->getPaletteManager()->grabPalette(palette, 0, PALETTE_COUNT);
 }
 
+/**
+ * Set the palette
+ */
 void Screen::setPalette(const byte palette[PALETTE_SIZE]) {
 	g_system->getPaletteManager()->setPalette(palette, 0, PALETTE_COUNT);
 }
 
+/**
+ * Fades from the currently active palette to the passed palette
+ */
 int Screen::equalizePalette(const byte palette[PALETTE_SIZE]) {
 	int total = 0;
 	byte tempPalette[PALETTE_SIZE];
diff --git a/engines/sherlock/sherlock.cpp b/engines/sherlock/sherlock.cpp
index 49230f22de..e3d137a3a3 100644
--- a/engines/sherlock/sherlock.cpp
+++ b/engines/sherlock/sherlock.cpp
@@ -69,6 +69,9 @@ SherlockEngine::~SherlockEngine() {
 	delete _res;
 }
 
+/**
+ * Does basic initialization of the game engine
+ */
 void SherlockEngine::initialize() {
 	initGraphics(SHERLOCK_SCREEN_WIDTH, SHERLOCK_SCREEN_HEIGHT, false);
 
@@ -93,7 +96,11 @@ void SherlockEngine::initialize() {
 	_ui = new UserInterface(this);
 }
 
+/**
+ * Main method for running the game
+ */
 Common::Error SherlockEngine::run() {
+	// Initialize the engine
 	initialize();
 
 	// If requested, load a savegame instead of showing the intro
@@ -133,6 +140,9 @@ Common::Error SherlockEngine::run() {
 	return Common::kNoError;
 }
 
+/**
+ * Main loop for displaying a scene and handling all that occurs within it
+ */
 void SherlockEngine::sceneLoop() {
 	while (!shouldQuit() && _scene->_goToScene == -1) {
 		// See if a script needs to be completed from either a goto room code,
@@ -171,7 +181,6 @@ void SherlockEngine::handleInput() {
 	_ui->handleInput();
 }
 
-
 /**
  * Read the state of a global flag
  */
@@ -193,6 +202,9 @@ void SherlockEngine::setFlags(int flagNum) {
 	_scene->checkSceneFlags(true);
 }
 
+/**
+ * Saves game configuration information
+ */
 void SherlockEngine::saveConfig() {
 	// TODO
 }
diff --git a/engines/sherlock/talk.cpp b/engines/sherlock/talk.cpp
index 603f47a446..d05c09ab38 100644
--- a/engines/sherlock/talk.cpp
+++ b/engines/sherlock/talk.cpp
@@ -100,6 +100,9 @@ Talk::Talk(SherlockEngine *vm): _vm(vm) {
 	_scriptCurrentIndex = -1;
 }
 
+/**
+ * Sets talk sequences
+ */
 void Talk::setSequences(const byte *talkSequences, const byte *stillSequences, int maxPeople) {
 	for (int idx = 0; idx < maxPeople; ++idx) {
 		STILL_SEQUENCES.push_back(TalkSequences(stillSequences));
@@ -1726,6 +1729,9 @@ int Talk::waitForMore(int delay) {
 	return key2;
 }
 
+/**
+ * Pops an entry off of the script stack
+ */
 void Talk::popStack() {
 	if (!_scriptStack.empty()) {
 		ScriptStackEntry scriptEntry = _scriptStack.pop();
diff --git a/engines/sherlock/user_interface.cpp b/engines/sherlock/user_interface.cpp
index e7e7981966..f60e63a574 100644
--- a/engines/sherlock/user_interface.cpp
+++ b/engines/sherlock/user_interface.cpp
@@ -188,6 +188,9 @@ void Settings::drawInteface(bool flag) {
 	}
 }
 
+/**
+ * Draws the buttons for the settings dialog
+ */
 int Settings::drawButtons(const Common::Point &pt, int _key) {
 	Events &events = *_vm->_events;
 	People &people = *_vm->_people;
@@ -259,7 +262,6 @@ int Settings::drawButtons(const Common::Point &pt, int _key) {
 	return found;
 }
 
-
 /*----------------------------------------------------------------*/
 
 UserInterface::UserInterface(SherlockEngine *vm) : _vm(vm) {
@@ -298,6 +300,9 @@ UserInterface::~UserInterface() {
 	delete _controlPanel;
 }
 
+/**
+ * Resets the user interface
+ */
 void UserInterface::reset() {
 	_oldKey = -1;
 	_help = _oldHelp = -1;
@@ -1962,6 +1967,12 @@ void UserInterface::doTalkControl() {
 	}
 }
 
+/**
+ * Handles events when the Journal is active.
+ * @remarks		Whilst this would in theory be better in the Journal class, since it displays in
+ *		the user interface, it uses so many internal UI fields, that it sort of made some sense 
+ *		to put it in the UserInterface class.
+ */
 void UserInterface::journalControl() {
 	Events &events = *_vm->_events;
 	Journal &journal = *_vm->_journal;
@@ -2013,6 +2024,9 @@ void UserInterface::journalControl() {
 
 /**
  * Handles input when the settings window is being shown
+ * @remarks		Whilst this would in theory be better in the Journal class, since it displays in
+ *		the user interface, it uses so many internal UI fields, that it sort of made some sense
+ *		to put it in the UserInterface class.
  */
 void UserInterface::doControls() {
 	Events &events = *_vm->_events;
@@ -2702,5 +2716,4 @@ void UserInterface::checkAction(ActionType &action, const char *const messages[]
 	events.setCursor(ARROW);
 }
 
-
 } // End of namespace Sherlock