SCI: Improve comments in GuestAdditions

1 files changed, 79 insertions, 11 deletions

diff --git a/engines/sci/engine/guest_additions.h b/engines/sci/engine/guest_additions.h
index 45d418bcba..9e5100d4a1 100644
--- a/engines/sci/engine/guest_additions.h
+++ b/engines/sci/engine/guest_additions.h
@@ -37,11 +37,13 @@ class SegManager;
  * The GuestAdditions class hooks into the SCI virtual machine to provide
  * enhanced interactions between the ScummVM GUI and the game engine. Currently,
  * this enhanced functionality encompasses synchronisation of audio volumes and
- * other audio-related settings.
+ * other audio-related settings, and integration of the ScummVM GUI when saving
+ * and loading game states.
  *
- * Some parts of the audio sync are applied as script patches using the normal
- * ScriptPatcher mechanism. These patches are designed to prevent the game from
- * resetting to a default volume when starting up or loading a save.
+ * NOTE: Some parts of the code used to manage audio sync are applied as script
+ * patches using the normal ScriptPatcher mechanism. These patches prevent the
+ * game from resetting audio volumes to defaults when starting up, and prevent
+ * the game from restoring audio volumes stored inside of a save game.
  */
 class GuestAdditions {
 public:
@@ -51,7 +53,7 @@ public:
 
 	/**
 	 * Synchronises audio volume settings from ScummVM to the game. Called
-	 * whenever the ScummVM launcher is dismissed.
+	 * whenever the ScummVM global menu is dismissed.
 	 */
 	void syncSoundSettings() const;
 
@@ -149,23 +151,52 @@ public:
 
 public:
 	/**
-	 * Patches game scripts to hook into the ScummVM launcher UI when a user
-	 * tries to save or restore a game from inside the game.
+	 * Patches game scripts to use the ScummVM save/load dialogue instead of the
+	 * game's native save/load dialogue when a user tries to save or restore a
+	 * game from inside the game.
 	 */
 	void patchGameSaveRestore() const;
 
 private:
+	/**
+	 * Patches the ScummVM save/load dialogue into the game for SCI16 games that
+	 * use Game::save and Game::restore.
+	 */
 	void patchGameSaveRestoreSCI16() const;
 
 #ifdef ENABLE_SCI32
 public:
+	/**
+	 * Finds the correct save file number and description to save or load and
+	 * returns it to the VM. For user-interactive save file lookup, this method
+	 * displays the ScummVM save/load dialogue. For delayed restores, it returns
+	 * the save game number sent by the ScummVM launcher without prompting the
+	 * user.
+	 */
 	reg_t kScummVMSaveLoad(EngineState *s, int argc, reg_t *argv) const;
 
 private:
+	/**
+	 * Patches the ScummVM save/load dialogue into SCI32 games that use
+	 * SRDialog.
+	 */
 	void patchGameSaveRestoreSCI32(Script &script) const;
+
+	/**
+	 * Patches the ScummVM save/load dialogue into Torin.
+	 */
 	void patchGameSaveRestoreTorin(Script &script) const;
 
+	/**
+	 * Prompts for a save game and returns it to game scripts using default
+	 * SRDialog game class semantics.
+	 */
 	reg_t promptSaveRestoreDefault(EngineState *s, int argc, reg_t *argv) const;
+
+	/**
+	 * Prompts for a save game and returns it to game scripts using Torin's
+	 * custom NewGame class semantics.
+	 */
 	reg_t promptSaveRestoreTorin(EngineState *s, int argc, reg_t *argv) const;
 #endif
 
@@ -174,12 +205,16 @@ private:
 
 private:
 	/**
-	 * Invokes the game's restore mechanism to load a save game that was
-	 * selected from the ScummVM launcher.
+	 * Invokes the game's save restore mechanism to load a save game that was
+	 * selected in the ScummVM launcher when the game was started.
 	 */
 	bool restoreFromLauncher() const;
 
 #ifdef ENABLE_SCI32
+	/**
+	 * If true, GuestAdditions is in the process of handling a delayed game
+	 * restore from the ScummVM launcher or global menu.
+	 */
 	mutable bool _restoring;
 #endif
 
@@ -188,20 +223,34 @@ private:
 
 private:
 	/**
-	 * true if the message type (text/speech/text+speech) has been synchronised
+	 * True if the message type (text/speech/text+speech) has been synchronised
 	 * from ScummVM to the game.
 	 */
 	bool _messageTypeSynced;
 
 	/**
-	 * Synchronises the message type (speech/text/speech+text) from a ScummVM to
+	 * Synchronises the message type (speech/text/speech+text) from ScummVM to
 	 * a game.
 	 */
 	void syncMessageTypeFromScummVM() const;
 
+	/**
+	 * Synchronises the message type from ScummVM using the default strategy
+	 * (global90).
+	 */
 	void syncMessageTypeFromScummVMUsingDefaultStrategy() const;
+
 #ifdef ENABLE_SCI32
+	/**
+	 * Synchronises the message type from ScummVM using the strategy used by
+	 * Shivers (global211).
+	 */
 	void syncMessageTypeFromScummVMUsingShiversStrategy() const;
+
+	/**
+	 * Synchronises the message type from ScummVM using the strategy used by
+	 * LSL6hires (gameFlags).
+	 */
 	void syncMessageTypeFromScummVMUsingLSL6HiresStrategy() const;
 #endif
 
@@ -211,9 +260,23 @@ private:
 	 */
 	void syncMessageTypeToScummVM(const int index, const reg_t value);
 
+	/**
+	 * Synchronises the message type to ScummVM using the default strategy
+	 * (global90).
+	 */
 	void syncMessageTypeToScummVMUsingDefaultStrategy(const int index, const reg_t value);
+
 #ifdef ENABLE_SCI32
+	/**
+	 * Synchronises the message type to ScummVM using the strategy used by
+	 * Shivers (global211).
+	 */
 	void syncMessageTypeToScummVMUsingShiversStrategy(const int index, const reg_t value);
+
+	/**
+	 * Synchronises the message type to ScummVM using the strategy used by
+	 * LSL6hires (gameFlags).
+	 */
 	void syncMessageTypeToScummVMUsingLSL6HiresStrategy(const reg_t sendObj, Selector &selector, reg_t *argp);
 #endif
 
@@ -250,7 +313,12 @@ private:
 	 */
 	void syncGK1StartupVolumeFromScummVM(const int index, const reg_t value) const;
 
+	/**
+	 * Synchronises audio volume settings from ScummVM to GK1 when the game is
+	 * running.
+	 */
 	void syncGK1VolumeFromScummVM(const int16 musicVolume, const int16 dacVolume) const;
+
 	void syncGK2VolumeFromScummVM(const int16 musicVolume) const;
 	void syncLSL6HiresVolumeFromScummVM(const int16 musicVolume) const;
 	void syncTorinVolumeFromScummVM(const int16 musicVolume, const int16 sfxVolume, const int16 speechVolume) const;