libcommon: Continued cleaning up savegame writing/reading

doomsday/plugins/common/include/mapstatereader.h

@@ -29,6 +29,7 @@
  * Performs saved game map state deserialization.
  *
  * @ingroup libcommon
+ * @see MapStateWriter
  */
 class MapStateReader
 {

doomsday/plugins/common/include/mapstatewriter.h

@@ -27,6 +27,7 @@
  * Performs saved game map state serialization.
  *
  * @ingroup libcommon
+ * @see MapStateReader
  */
 class MapStateWriter
 {

doomsday/plugins/common/include/p_saveg.h

@@ -53,12 +53,12 @@ dd_bool SV_HxHaveMapStateForSlot(int slot, uint map);
 /**
  * Save the current game state to the specified @a slot number.
  *
- * @param name  Textual description to include in the save info. Can be @c 0
- *              in which case a description will be auto-generated.
+ * @param description  Textual description to include in the save info. Can be @c 0
+ *                     in which case a description will be auto-generated.
  *
  * @return  @c true iff the game state was saved successfully.
  */
-dd_bool SV_SaveGame(int slot, char const *name);
+dd_bool SV_SaveGame(int slot, char const *description);
 
 /**
  * Load the game state associated with the specified @a slot number.
@@ -117,7 +117,6 @@ mobj_t *SV_GetArchiveThing(ThingSerialId thingid, void *address);
 void SV_TranslateLegacyMobjFlags(mobj_t *mo, int ver);
 
 #if __JHEXEN__
-void SV_HxInitBaseSlot(void);
 void SV_HxSaveHubMap(void);
 void SV_HxLoadHubMap(void);
 
@@ -131,9 +130,9 @@ void SV_HxBackupPlayersInHub(playerbackup_t playerBackup[MAXPLAYERS]);
 
 /**
  * @param playerBackup  Player state backup.
- * @param entryPoint  Logical identifier for the entry point used to enter the map.
+ * @param mapEntrance   Logical entry point number used to enter the map.
  */
-void SV_HxRestorePlayersInHub(playerbackup_t playerBackup[MAXPLAYERS], uint entryPoint);
+void SV_HxRestorePlayersInHub(playerbackup_t playerBackup[MAXPLAYERS], uint mapEntrance);
 #endif
 
 void SV_InitThingArchiveForLoad(uint size);

doomsday/plugins/common/include/p_saveio.h

@@ -43,11 +43,6 @@ typedef enum savestatesegment_e {
     ASEG_WORLDSCRIPTDATA   // Hexen only
 } savestatesegment_t;
 
-enum {
-    SV_OK = 0,
-    SV_INVALIDFILENAME
-};
-
 #ifdef __cplusplus
 extern "C" {
 #endif

doomsday/plugins/common/include/saveinfo.h

@@ -76,7 +76,7 @@ class SaveInfo
      * @see G_GenerateSessionId()
      */
     uint sessionId() const;
-    void setSessionId(uint newGameId);
+    void setSessionId(uint newSessionId);
 
     /**
      * Returns the URI of the @em current map of the game session.
@@ -142,8 +142,8 @@ SaveInfo *SaveInfo_Copy(SaveInfo *info, SaveInfo const *other);
 dd_bool SaveInfo_IsLoadable(SaveInfo *info);
 Str const *SaveInfo_Description(SaveInfo const *info);
 void SaveInfo_SetDescription(SaveInfo *info, Str const *newName);
-uint SaveInfo_GameId(SaveInfo const *info);
-void SaveInfo_SetGameId(SaveInfo *info, uint newGameId);
+uint SaveInfo_SessionId(SaveInfo const *info);
+void SaveInfo_SetSessionId(SaveInfo *info, uint newSessionId);
 void SaveInfo_Write(SaveInfo *info, Writer *writer);
 void SaveInfo_Read(SaveInfo *info, Reader *reader);
 #if __JHEXEN__

doomsday/plugins/common/include/saveslots.h

@@ -48,7 +48,7 @@ class SaveSlots
      */
     SaveSlots(int numSlots);
 
-    void clearSaveInfo();
+    void clearAllSaveInfo();
 
     /**
      * Force an update of the cached game-save info. To be called (sparingly) at strategic
@@ -66,11 +66,15 @@ class SaveSlots
 
     /**
      * Returns @c true iff @a slot is a valid logical slot number (in range).
+     *
+     * @see slotCount()
      */
     bool isValidSlot(int slot) const;
 
     /**
      * Composes the textual identifier/name for save @a slot.
+     *
+     * @see parseSlotIdentifier()
      */
     AutoStr *composeSlotIdentifier(int slot) const;
 
@@ -87,33 +91,37 @@ class SaveSlots
      *                 <quick> = The currently nominated "quick save" slot.
      *             Pass 3: Check for a logical save slot number.
      *
-     * @return  Save slot identifier of the slot else @c -1
+     * @return  The parsed slot number if valid; otherwise @c -1
+     *
+     * @see composeSlotIdentifier()
      */
     int parseSlotIdentifier(char const *str) const;
 
     /**
      * Lookup a save slot by searching for a match on game-save description. The search is in
      * ascending logical slot order 0...N (where N is the number of available save slots).
      *
-     * @param description  Description of the game-save to look for. Case insensitive.
+     * @param description  Description of the game-save to look for (not case sensitive).
      *
      * @return  Logical slot number of the found game-save else @c -1
      */
     int findSlotWithSaveDescription(char const *description) const;
 
     /**
-     * Returns @c true iff a game-save is present for logical save @a slot.
+     * Returns @c true iff a saved game state exists for save @a slot.
      */
     bool slotInUse(int slot) const;
 
     /**
-     * Returns @c true iff @a slot is user-writable save slot (i.e., its not one of the special
-     * slots such as @em auto).
+     * Returns @c true iff save @a slot is user-writable (i.e., not a special slot, such as
+     * the @em auto and @em base slots).
      */
     bool slotIsUserWritable(int slot) const;
 
     /**
      * Returns the SaveInfo associated with the logical save @a slot.
+     *
+     * @see isValidSlot()
      */
     SaveInfo &saveInfo(int slot) const;
 
@@ -122,7 +130,9 @@ class SaveSlots
     }
 
     /**
-     * Deletes all save game files associated with a slot number.
+     * Deletes all save game files associated with the specified save @a slot.
+     *
+     * @see isValidSlot()
      */
     void clearSlot(int slot);
 
@@ -138,9 +148,9 @@ class SaveSlots
     void copySlot(int sourceSlot, int destSlot);
 
     /**
-     * Compose the (possibly relative) path to save state associated with the logical save @a slot.
+     * Compose the (possibly relative) file path to the game state associated with save @a slot.
      *
-     * @param slot  Logical save slot identifier.
+     * @param slot  Slot to compose the identifier of.
      * @param map   If @c >= 0 include this logical map index in the composed path.
      *
      * @return  The composed path if reachable (else a zero-length string).
@@ -171,8 +181,7 @@ typedef void *SaveSlots;
 SaveSlots *SaveSlots_New(int slotCount);
 void SaveSlots_Delete(SaveSlots *sslots);
 
-void SaveSlots_ClearSaveInfo(SaveSlots *sslots);
-void SaveSlots_BuildSaveInfo(SaveSlots *sslots);
+void SaveSlots_ClearAllSaveInfo(SaveSlots *sslots);
 void SaveSlots_UpdateAllSaveInfo(SaveSlots *sslots);
 int SaveSlots_SlotCount(SaveSlots const *sslots);
 dd_bool SaveSlots_IsValidSlot(SaveSlots const *sslots, int slot);

doomsday/plugins/common/src/g_game.c

@@ -2165,7 +2165,7 @@ void G_DoReborn(int plrNum)
 static void G_InitNewGame(void)
 {
 #if __JHEXEN__
-    SV_HxInitBaseSlot();
+    SaveSlots_ClearSlot(saveSlots, BASE_SLOT);
 #endif
 
     /// @todo Do not clear this save slot. Instead we should set a game state

doomsday/plugins/common/src/mapstatereader.cpp

@@ -58,6 +58,8 @@ DENG2_PIMPL(MapStateReader)
             /// @throw ReadError Failed alignment check.
             throw ReadError("MapStateReader::checkSegment", "Corrupt save game, segment " + de::String::number(segId) + " failed alignment check");
         }
+#else
+        DENG_UNUSED(segId);
 #endif
     }