(svn r21281) -Doc: Add doxygen comments to saveload code.

2 files changed, 245 insertions, 41 deletions

diff --git a/src/saveload/saveload.cpp b/src/saveload/saveload.cpp
index 557ea29f1..cf2ddb2b5 100644
--- a/src/saveload/saveload.cpp
+++ b/src/saveload/saveload.cpp
@@ -304,6 +304,7 @@ extern const ChunkHandler _labelmaps_chunk_handlers[];
 extern const ChunkHandler _airport_chunk_handlers[];
 extern const ChunkHandler _object_chunk_handlers[];
 
+/** Array of all chunks in a savegame, \c NULL terminated. */
 static const ChunkHandler * const _chunk_handlers[] = {
 	_gamelog_chunk_handlers,
 	_map_chunk_handlers,
@@ -2273,6 +2274,7 @@ static SaveOrLoadResult SaveFileToDisk(bool threaded)
 	}
 }
 
+/** Thread run function for saving the file to disk. */
 static void SaveFileToDiskThread(void *arg)
 {
 	SaveFileToDisk(true);
@@ -2291,10 +2293,10 @@ void WaitTillSaved()
  * Main Save or Load function where the high-level saveload functions are
  * handled. It opens the savegame, selects format and checks versions
  * @param filename The name of the savegame being created/loaded
- * @param mode Save or load. Load can also be a TTD(Patch) game. Use SL_LOAD, SL_OLD_LOAD or SL_SAVE
+ * @param mode Save or load mode. Load can also be a TTD(Patch) game. Use #SL_LOAD, #SL_OLD_LOAD, #SL_LOAD_CHECK, or #SL_SAVE.
  * @param sb The sub directory to save the savegame in
  * @param threaded True when threaded saving is allowed
- * @return Return the results of the action. SL_OK, SL_ERROR or SL_REINIT ("unload" the game)
+ * @return Return the result of the action. #SL_OK, #SL_ERROR, or #SL_REINIT ("unload" the game)
  */
 SaveOrLoadResult SaveOrLoad(const char *filename, int mode, Subdirectory sb, bool threaded)
 {
diff --git a/src/saveload/saveload.h b/src/saveload/saveload.h
index cf7ff8213..7bb84e81f 100644
--- a/src/saveload/saveload.h
+++ b/src/saveload/saveload.h
@@ -27,14 +27,15 @@ enum SaveOrLoadResult {
 	SL_REINIT = 2, ///< error that was caught in the middle of updating game state, need to clear it. (can only happen during load)
 };
 
+/** Save or load mode. @see SaveOrLoad */
 enum SaveOrLoadMode {
-	SL_INVALID    = -1,
-	SL_LOAD       =  0,
-	SL_SAVE       =  1,
-	SL_OLD_LOAD   =  2,
-	SL_PNG        =  3,
-	SL_BMP        =  4,
-	SL_LOAD_CHECK =  5,
+	SL_INVALID    = -1, ///< Invalid mode.
+	SL_LOAD       =  0, ///< Load game.
+	SL_SAVE       =  1, ///< Save game.
+	SL_OLD_LOAD   =  2, ///< Load old game.
+	SL_PNG        =  3, ///< Load PNG file (height map).
+	SL_BMP        =  4, ///< Load BMP file (height map).
+	SL_LOAD_CHECK =  5, ///< Load for game preview.
 };
 
 /** Types of save games. */
@@ -58,39 +59,43 @@ void DoExitSave();
 typedef void ChunkSaveLoadProc();
 typedef void AutolengthProc(void *arg);
 
+/** Handlers and description of chunk. */
 struct ChunkHandler {
-	uint32 id;
-	ChunkSaveLoadProc *save_proc;
-	ChunkSaveLoadProc *load_proc;
-	ChunkSaveLoadProc *ptrs_proc;
-	ChunkSaveLoadProc *load_check_proc;
-	uint32 flags;
+	uint32 id;                          ///< Unique ID (4 letters).
+	ChunkSaveLoadProc *save_proc;       ///< Save procedure of the chunk.
+	ChunkSaveLoadProc *load_proc;       ///< Load procedure of the chunk.
+	ChunkSaveLoadProc *ptrs_proc;       ///< Manipulate pointers in the chunk.
+	ChunkSaveLoadProc *load_check_proc; ///< Load procedure for game preview.
+	uint32 flags;                       ///< Flags of the chunk. @see ChunkType
 };
 
 struct NullStruct {
 	byte null;
 };
 
+/** Type of reference (#SLE_REF, #SLE_CONDREF). */
 enum SLRefType {
-	REF_ORDER         = 0,
-	REF_VEHICLE       = 1,
-	REF_STATION       = 2,
-	REF_TOWN          = 3,
-	REF_VEHICLE_OLD   = 4,
-	REF_ROADSTOPS     = 5,
-	REF_ENGINE_RENEWS = 6,
-	REF_CARGO_PACKET  = 7,
-	REF_ORDERLIST     = 8,
+	REF_ORDER         = 0, ///< Load/save a reference to an order.
+	REF_VEHICLE       = 1, ///< Load/save a reference to a vehicle.
+	REF_STATION       = 2, ///< Load/save a reference to a station.
+	REF_TOWN          = 3, ///< Load/save a reference to a town.
+	REF_VEHICLE_OLD   = 4, ///< Load/save an old-style reference to a vehicle (for pre-4.4 savegames).
+	REF_ROADSTOPS     = 5, ///< Load/save a reference to a bus/truck stop.
+	REF_ENGINE_RENEWS = 6, ///< Load/save a reference to an engine renewal (autoreplace).
+	REF_CARGO_PACKET  = 7, ///< Load/save a reference to a cargo packet.
+	REF_ORDERLIST     = 8, ///< Load/save a reference to an orderlist.
 };
 
+/** Highest possible savegame version. */
 #define SL_MAX_VERSION 255
 
+/** Flags of a chunk. */
 enum ChunkType {
 	CH_RIFF         =  0,
 	CH_ARRAY        =  1,
 	CH_SPARSE_ARRAY =  2,
 	CH_TYPE_MASK    =  3,
-	CH_LAST         =  8,
+	CH_LAST         =  8, ///< Last chunk in this array.
 	CH_AUTO_LENGTH  = 16,
 };
 
@@ -175,12 +180,13 @@ enum VarTypes {
 
 typedef uint32 VarType;
 
+/** Type of data saved. */
 enum SaveLoadTypes {
-	SL_VAR         =  0,
-	SL_REF         =  1,
-	SL_ARR         =  2,
-	SL_STR         =  3,
-	SL_LST         =  4,
+	SL_VAR         =  0, ///< Save/load a variable.
+	SL_REF         =  1, ///< Save/load a reference.
+	SL_ARR         =  2, ///< Save/load an array.
+	SL_STR         =  3, ///< Save/load a string.
+	SL_LST         =  4, ///< Save/load a list.
 	/* non-normal save-load types */
 	SL_WRITEBYTE   =  8,
 	SL_VEH_INCLUDE =  9,
@@ -188,7 +194,7 @@ enum SaveLoadTypes {
 	SL_END         = 15
 };
 
-typedef byte SaveLoadType;
+typedef byte SaveLoadType; ///< Save/load type. @see SaveLoadTypes
 
 /** SaveLoad type struct. Do NOT use this directly but use the SLE_ macros defined just below! */
 struct SaveLoad {
@@ -205,56 +211,247 @@ struct SaveLoad {
 	void *address;       ///< address of variable OR offset of variable in the struct (max offset is 65536)
 };
 
-/* Same as SaveLoad but global variables are used (for better readability); */
+/** Same as #SaveLoad but global variables are used (for better readability); */
 typedef SaveLoad SaveLoadGlobVarList;
 
-/* Simple variables, references (pointers) and arrays */
+/**
+ * Storage of simple variables, references (pointers), and arrays.
+ * @param cmd      Load/save type. @see SaveLoadType
+ * @param base     Name of the class or struct containing the variable.
+ * @param variable Name of the variable in the class or struct referenced by \a base.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param from     First savegame version that has the field.
+ * @param to       Last savegame version that has the field.
+ * @note In general, it is better to use one of the SLE_* macros below.
+ */
 #define SLE_GENERAL(cmd, base, variable, type, length, from, to) {false, cmd, type, length, from, to, (void*)cpp_offsetof(base, variable)}
+
+/**
+ * Storage of a variable in some savegame versions.
+ * @param base     Name of the class or struct containing the variable.
+ * @param variable Name of the variable in the class or struct referenced by \a base.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param from     First savegame version that has the field.
+ * @param to       Last savegame version that has the field.
+ */
 #define SLE_CONDVAR(base, variable, type, from, to) SLE_GENERAL(SL_VAR, base, variable, type, 0, from, to)
+
+/**
+ * Storage of a reference in some savegame versions.
+ * @param base     Name of the class or struct containing the variable.
+ * @param variable Name of the variable in the class or struct referenced by \a base.
+ * @param type     Type of the reference, a value from #SLRefType.
+ * @param from     First savegame version that has the field.
+ * @param to       Last savegame version that has the field.
+ */
 #define SLE_CONDREF(base, variable, type, from, to) SLE_GENERAL(SL_REF, base, variable, type, 0, from, to)
+
+/**
+ * Storage of an array in some savegame versions.
+ * @param base     Name of the class or struct containing the array.
+ * @param variable Name of the variable in the class or struct referenced by \a base.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param length   Number of elements in the array.
+ * @param from     First savegame version that has the array.
+ * @param to       Last savegame version that has the array.
+ */
 #define SLE_CONDARR(base, variable, type, length, from, to) SLE_GENERAL(SL_ARR, base, variable, type, length, from, to)
+
+/**
+ * Storage of a string in some savegame versions.
+ * @param base     Name of the class or struct containing the string.
+ * @param variable Name of the variable in the class or struct referenced by \a base.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param length   Number of elements in the string (only used for fixed size buffers).
+ * @param from     First savegame version that has the string.
+ * @param to       Last savegame version that has the string.
+ */
 #define SLE_CONDSTR(base, variable, type, length, from, to) SLE_GENERAL(SL_STR, base, variable, type, length, from, to)
+
+/**
+ * Storage of a list in some savegame versions.
+ * @param base     Name of the class or struct containing the list.
+ * @param variable Name of the variable in the class or struct referenced by \a base.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param from     First savegame version that has the list.
+ * @param to       Last savegame version that has the list.
+ */
 #define SLE_CONDLST(base, variable, type, from, to) SLE_GENERAL(SL_LST, base, variable, type, 0, from, to)
 
+/**
+ * Storage of a variable in every version of a savegame.
+ * @param base     Name of the class or struct containing the variable.
+ * @param variable Name of the variable in the class or struct referenced by \a base.
+ * @param type     Storage of the data in memory and in the savegame.
+ */
 #define SLE_VAR(base, variable, type) SLE_CONDVAR(base, variable, type, 0, SL_MAX_VERSION)
+
+/**
+ * Storage of a reference in every version of a savegame.
+ * @param base     Name of the class or struct containing the variable.
+ * @param variable Name of the variable in the class or struct referenced by \a base.
+ * @param type     Type of the reference, a value from #SLRefType.
+ */
 #define SLE_REF(base, variable, type) SLE_CONDREF(base, variable, type, 0, SL_MAX_VERSION)
+
+/**
+ * Storage of an array in every version of a savegame.
+ * @param base     Name of the class or struct containing the array.
+ * @param variable Name of the variable in the class or struct referenced by \a base.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param length   Number of elements in the array.
+ */
 #define SLE_ARR(base, variable, type, length) SLE_CONDARR(base, variable, type, length, 0, SL_MAX_VERSION)
+
+/**
+ * Storage of a string in every savegame version.
+ * @param base     Name of the class or struct containing the string.
+ * @param variable Name of the variable in the class or struct referenced by \a base.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param length   Number of elements in the string (only used for fixed size buffers).
+ */
 #define SLE_STR(base, variable, type, length) SLE_CONDSTR(base, variable, type, length, 0, SL_MAX_VERSION)
+
+/**
+ * Storage of a list in every savegame version.
+ * @param base     Name of the class or struct containing the list.
+ * @param variable Name of the variable in the class or struct referenced by \a base.
+ * @param type     Storage of the data in memory and in the savegame.
+ */
 #define SLE_LST(base, variable, type) SLE_CONDLST(base, variable, type, 0, SL_MAX_VERSION)
+
+/**
+ * Empty space in every savegame version.
+ * @param length Length of the empty space.
+ */
 #define SLE_NULL(length) SLE_CONDNULL(length, 0, SL_MAX_VERSION)
 
+/**
+ * Empty space in some savegame versions.
+ * @param length Length of the empty space.
+ * @param from   First savegame version that has the empty space.
+ * @param to     Last savegame version that has the empty space.
+ */
 #define SLE_CONDNULL(length, from, to) SLE_CONDARR(NullStruct, null, SLE_FILE_U8 | SLE_VAR_NULL | SLF_CONFIG_NO, length, from, to)
 
-/* Translate values ingame to different values in the savegame and vv */
+/** Translate values ingame to different values in the savegame and vv. */
 #define SLE_WRITEBYTE(base, variable, value) SLE_GENERAL(SL_WRITEBYTE, base, variable, 0, 0, value, value)
 
 #define SLE_VEH_INCLUDE() {false, SL_VEH_INCLUDE, 0, 0, 0, SL_MAX_VERSION, NULL}
 #define SLE_ST_INCLUDE() {false, SL_ST_INCLUDE, 0, 0, 0, SL_MAX_VERSION, NULL}
 
-/* End marker */
+/** End marker of a struct/class save or load. */
 #define SLE_END() {false, SL_END, 0, 0, 0, 0, NULL}
 
-/* Simple variables, references (pointers) and arrays, but for global variables */
+/**
+ * Storage of global simple variables, references (pointers), and arrays.
+ * @param cmd      Load/save type. @see SaveLoadType
+ * @param variable Name of the global variable.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param from     First savegame version that has the field.
+ * @param to       Last savegame version that has the field.
+ * @note In general, it is better to use one of the SLEG_* macros below.
+ */
 #define SLEG_GENERAL(cmd, variable, type, length, from, to) {true, cmd, type, length, from, to, (void*)&variable}
 
+/**
+ * Storage of a global variable in some savegame versions.
+ * @param variable Name of the global variable.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param from     First savegame version that has the field.
+ * @param to       Last savegame version that has the field.
+ */
 #define SLEG_CONDVAR(variable, type, from, to) SLEG_GENERAL(SL_VAR, variable, type, 0, from, to)
+
+/**
+ * Storage of a global reference in some savegame versions.
+ * @param variable Name of the global variable.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param from     First savegame version that has the field.
+ * @param to       Last savegame version that has the field.
+ */
 #define SLEG_CONDREF(variable, type, from, to) SLEG_GENERAL(SL_REF, variable, type, 0, from, to)
+
+/**
+ * Storage of a global array in some savegame versions.
+ * @param variable Name of the global variable.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param length   Number of elements in the array.
+ * @param from     First savegame version that has the array.
+ * @param to       Last savegame version that has the array.
+ */
 #define SLEG_CONDARR(variable, type, length, from, to) SLEG_GENERAL(SL_ARR, variable, type, length, from, to)
+
+/**
+ * Storage of a global string in some savegame versions.
+ * @param variable Name of the global variable.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param length   Number of elements in the string (only used for fixed size buffers).
+ * @param from     First savegame version that has the string.
+ * @param to       Last savegame version that has the string.
+ */
 #define SLEG_CONDSTR(variable, type, length, from, to) SLEG_GENERAL(SL_STR, variable, type, length, from, to)
+
+/**
+ * Storage of a global list in some savegame versions.
+ * @param variable Name of the global variable.
+ * @param type     Storage of the data in memory and in the savegame.
+ * @param from     First savegame version that has the list.
+ * @param to       Last savegame version that has the list.
+ */
 #define SLEG_CONDLST(variable, type, from, to) SLEG_GENERAL(SL_LST, variable, type, 0, from, to)
 
+/**
+ * Storage of a global variable in every savegame version.
+ * @param variable Name of the global variable.
+ * @param type     Storage of the data in memory and in the savegame.
+ */
 #define SLEG_VAR(variable, type) SLEG_CONDVAR(variable, type, 0, SL_MAX_VERSION)
+
+/**
+ * Storage of a global reference in every savegame version.
+ * @param variable Name of the global variable.
+ * @param type     Storage of the data in memory and in the savegame.
+ */
 #define SLEG_REF(variable, type) SLEG_CONDREF(variable, type, 0, SL_MAX_VERSION)
+
+/**
+ * Storage of a global array in every savegame version.
+ * @param variable Name of the global variable.
+ * @param type     Storage of the data in memory and in the savegame.
+ */
 #define SLEG_ARR(variable, type) SLEG_CONDARR(variable, type, lengthof(variable), 0, SL_MAX_VERSION)
+
+/**
+ * Storage of a global string in every savegame version.
+ * @param variable Name of the global variable.
+ * @param type     Storage of the data in memory and in the savegame.
+ */
 #define SLEG_STR(variable, type) SLEG_CONDSTR(variable, type, lengthof(variable), 0, SL_MAX_VERSION)
+
+/**
+ * Storage of a global list in every savegame version.
+ * @param variable Name of the global variable.
+ * @param type     Storage of the data in memory and in the savegame.
+ */
 #define SLEG_LST(variable, type) SLEG_CONDLST(variable, type, 0, SL_MAX_VERSION)
 
+/**
+ * Empty global space in some savegame versions.
+ * @param length Length of the empty space.
+ * @param from   First savegame version that has the empty space.
+ * @param to     Last savegame version that has the empty space.
+ */
 #define SLEG_CONDNULL(length, from, to) {true, SL_ARR, SLE_FILE_U8 | SLE_VAR_NULL | SLF_CONFIG_NO, length, from, to, (void*)NULL}
 
+/** End marker of global variables save or load. */
 #define SLEG_END() {true, SL_END, 0, 0, 0, 0, NULL}
 
 /**
- * Checks if the savegame is below major.minor.
+ * Checks if the savegame is below \a major.\a minor.
+ * @param major Major number of the version to check against.
+ * @param minor Minor number of the version to check against.
+ * @return Savegame version is less than the \a major version, or has equal \a major version and a smaller \a minor version.
  */
 static inline bool CheckSavegameVersionOldStyle(uint16 major, byte minor)
 {
@@ -264,7 +461,9 @@ static inline bool CheckSavegameVersionOldStyle(uint16 major, byte minor)
 }
 
 /**
- * Checks if the savegame is below version.
+ * Checks if the savegame is below \a version.
+ * @param version First version that is too large.
+ * @return Savegame version equal or larger than \a version.
  */
 static inline bool CheckSavegameVersion(uint16 version)
 {
@@ -274,7 +473,10 @@ static inline bool CheckSavegameVersion(uint16 version)
 
 /**
  * Checks if some version from/to combination falls within the range of the
- * active savegame version
+ * active savegame version.
+ * @param version_from Lowest version number that falls within the range.
+ * @param version_to   Highest version number that falls within the range.
+ * @return Active savegame version falls within the given range.
  */
 static inline bool SlIsObjectCurrentlyValid(uint16 version_from, uint16 version_to)
 {
@@ -296,9 +498,9 @@ static inline VarType GetVarMemType(VarType type)
 }
 
 /**
- * Get the FileType of a setting. This describes the integer type
+ * Get the #FileType of a setting. This describes the integer type
  * as it is represented in a savegame/file
- * @param type VarType holding information about the variable-type
+ * @param type VarType holding information about the file-type
  * @param return the SLE_FILE_* part of a variable-type description
  */
 static inline VarType GetVarFileType(VarType type)