1 files changed, 106 insertions, 12 deletions

diff --git a/engines/sherlock/scene.h b/engines/sherlock/scene.h
index 9454a4e20b..0cbd775c56 100644
--- a/engines/sherlock/scene.h
+++ b/engines/sherlock/scene.h
@@ -57,14 +57,21 @@ struct BgFileHeader {
 
 
 	BgFileHeader();
-	void synchronize(Common::SeekableReadStream &s, bool isRoseTattoo);
+
+	/**
+	 * Load the data for the object
+	 */
+	void load(Common::SeekableReadStream &s, bool isRoseTattoo);
 };
 
-struct BgfileheaderInfo {
+struct BgFileHeaderInfo {
 	int _filesize;				// How long images are
 	int _maxFrames;				// How many unique frames in object
 	Common::String _filename;	// Filename of object
 
+	/**
+	 * Load the data for the object
+	 */
 	void load(Common::SeekableReadStream &s);
 };
 
@@ -78,6 +85,9 @@ public:
 	Common::String _dest;
 	int _image;					// Arrow image to use
 
+	/**
+	 * Load the data for the object
+	 */
 	void load(Common::SeekableReadStream &s, bool isRoseTattoo);
 };
 
@@ -86,6 +96,9 @@ struct SceneEntry {
 	int _startDir;
 	int _allow;
 
+	/**
+	 * Load the data for the object
+	 */
 	void load(Common::SeekableReadStream &s);
 };
 
@@ -93,11 +106,17 @@ struct SceneSound {
 	Common::String _name;
 	int _priority;
 
+	/**
+	 * Load the data for the object
+	 */
 	void load(Common::SeekableReadStream &s);
 };
 
-class ObjectArray: public Common::Array<Object> {
+class ObjectArray : public Common::Array<Object> {
 public:
+	/**
+	 * Retuurn the index of the passed object in the array
+	 */
 	int indexOf(const Object &obj) const;
 };
 
@@ -113,33 +132,61 @@ class Scene {
 private:
 	SherlockEngine *_vm;
 	Common::String _rrmName;
-	int _selector;
-	bool _lookHelp;
 	bool _loadingSavedGame;
 
+	/**
+	 * Loads the data associated for a given scene. The .BGD file's format is:
+	 * BGHEADER: Holds an index for the rest of the file
+	 * STRUCTS:  The objects for the scene
+	 * IMAGES:   The graphic information for the structures
+	 *
+	 * The _misc field of the structures contains the number of the graphic image
+	 * that it should point to after loading; _misc is then set to 0.
+	 */
 	bool loadScene(const Common::String &filename);
 
+	/**
+	 * Loads sounds for the scene
+	 */
 	void loadSceneSounds();
 
+	/**
+	 * Set objects to their current persistent state. This includes things such as
+	 * opening or moving them
+	 */
 	void checkSceneStatus();
 
+	/**
+	 * Checks scene objects against the player's inventory items. If there are any
+	 * matching names, it means the given item has already been picked up, and should
+	 * be hidden in the scene.
+	 */
 	void checkInventory();
 
+	/**
+	 * Set up any entrance co-ordinates or entrance canimations, and then transition
+	 * in the scene
+	 */
 	void transitionToScene();
 
+	/**
+	 * Checks all the background shapes. If a background shape is animating,
+	 * it will flag it as needing to be drawn. If a non-animating shape is
+	 * colliding with another shape, it will also flag it as needing drawing
+	 */
 	void checkBgShapes(ImageFrame *frame, const Common::Point &pt);
 
+	/**
+	 * Restores objects to the correct status. This ensures that things like being opened or moved
+	 * will remain the same on future visits to the scene
+	 */
 	void saveSceneStatus();
 
 public:
 	int _currentScene;
 	int _goToScene;
-	bool _changes;
 	bool _sceneStats[SCENES_COUNT][65];
 	bool _savedStats[SCENES_COUNT][9];
-	int _keyboardInput;
-	int _oldKey, _help, _oldHelp;
-	int _oldTemp, _temp;
 	bool _walkedInScene;
 	int _version;
 	bool _lzwMode;
@@ -165,37 +212,84 @@ public:
 	bool _doBgAnimDone;
 	int _tempFadeStyle;
 	int _cAnimFramePause;
-	bool _invLookFlag;
 public:
 	Scene(SherlockEngine *vm);
 	~Scene();
 
+	/**
+	 * Handles loading the scene specified by _goToScene
+	 */
 	void selectScene();
 
+	/**
+	 * Fres all the graphics and other dynamically allocated data for the scene
+	 */
 	void freeScene();
 
+	/**
+	 * Check the scene's objects against the game flags. If false is passed,
+	 * it means the scene has just been loaded. A value of true means that the scene
+	 * is in use (ie. not just loaded)
+	 */
 	void checkSceneFlags(bool mode);
 
+	/**
+	 * Check whether the passed area intersects with one of the scene's exits
+	 */
 	Exit *checkForExit(const Common::Rect &r);
 
+	/**
+	 * Attempt to start a canimation sequence. It will load the requisite graphics, and
+	 * then copy the canim object into the _canimShapes array to start the animation.
+	 *
+	 * @param cAnimNum		The canim object within the current scene
+	 * @param playRate		Play rate. 0 is invalid; 1=normal speed, 2=1/2 speed, etc.
+	 *		A negative playRate can also be specified to play the animation in reverse
+	 */
 	int startCAnim(int cAnimNum, int playRate);
 
+	/**
+	 * Scans through the object list to find one with a matching name, and will
+	 * call toggleHidden with all matches found. Returns the numer of matches found
+	 */
 	int toggleObject(const Common::String &name);
 
+	/**
+	 * Animate all objects and people.
+	 */
 	void doBgAnim();
 
-	void clearInfo();
-
+	/**
+	 * Attempts to find a background shape within the passed bounds. If found,
+	 * it will return the shape number, or -1 on failure.
+	 */
 	int findBgShape(const Common::Rect &r);
 
+	/**
+	 * Checks to see if the given position in the scene belongs to a given zone type.
+	 * If it is, the zone is activated and used just like a TAKL zone or aFLAG_SET zone.
+	 */
 	int checkForZones(const Common::Point &pt, int zoneType);
 
+	/**
+	 * Check which zone the the given position is located in.
+	 */
 	int whichZone(const Common::Point &pt);
 
+	/**
+	 * Returns the index of the closest zone to a given point.
+	 */
 	int closestZone(const Common::Point &pt);
 
+	/**
+	 * Update the screen back buffer with all of the scene objects which need
+	 * to be drawn
+	 */
 	void updateBackground();
 
+	/**
+	 * Synchronize the data for a savegame
+	 */
 	void synchronize(Common::Serializer &s);
 };