(svn r22500) -Doc: Fix and add fios doxygen documentation.

src/fios.cpp

@@ -63,7 +63,7 @@ int CDECL CompareFiosItems(const FiosItem *da, const FiosItem *db)
 	return r;
 }
 
-/** Clear the list */
+/** Free the list of savegames. */
 void FiosFreeSavegameList()
 {
 	_fios_items.Clear();
@@ -84,9 +84,9 @@ StringID FiosGetDescText(const char **path, uint64 *total_free)
 }
 
 /**
- * Browse to a new path based on the passed \a item.
+ * Browse to a new path based on the passed \a item, starting at #_fios_path.
- * @param *item #FiosItem object telling us what to do.
+ * @param *item Item telling us what to do.
- * @return A string if we have given a file as a target, otherwise \c NULL.
+ * @return A filename w/path if we reached a file, otherwise \c NULL.
  */
 const char *FiosBrowseTo(const FiosItem *item)
 {
@@ -142,6 +142,12 @@ const char *FiosBrowseTo(const FiosItem *item)
 	return NULL;
 }
 
+/**
+ * Make a save game or scenario filename from a name.
+ * @param buf Destination buffer for saving the filename.
+ * @param name Name of the file.
+ * @param size Length of buffer \a buf.
+ */
 void FiosMakeSavegameName(char *buf, const char *name, size_t size)
 {
 	const char *extension, *period;
@@ -168,6 +174,10 @@ void FiosMakeSavegameName(char *buf, const char *name, size_t size)
 #endif
 }
 
+/**
+ * Delete a file.
+ * @param name Filename to delete.
+ */
 bool FiosDelete(const char *name)
 {
 	char filename[512];
@@ -394,7 +404,6 @@ FiosType FiosGetSavegameListCallback(SaveLoadDialogMode mode, const char *file,
 /**
  * Get a list of savegames.
  * @param mode Save/load mode.
- * @return A pointer to an array of FiosItem representing all the files to be shown in the save/load dialog.
  * @see FiosGetFileList
  */
 void FiosGetSavegameList(SaveLoadDialogMode mode)
@@ -446,7 +455,6 @@ static FiosType FiosGetScenarioListCallback(SaveLoadDialogMode mode, const char
 /**
  * Get a list of scenarios.
  * @param mode Save/load mode.
- * @return A pointer to an array of FiosItem representing all the files to be shown in the save/load dialog.
  * @see FiosGetFileList
  */
 void FiosGetScenarioList(SaveLoadDialogMode mode)
@@ -511,7 +519,10 @@ static FiosType FiosGetHeightmapListCallback(SaveLoadDialogMode mode, const char
 	return type;
 }
 
-/* Get a list of Heightmaps */
+/**
+ * Get a list of heightmaps.
+ * @param mode Save/load mode.
+ */
 void FiosGetHeightmapList(SaveLoadDialogMode mode)
 {
 	static char *fios_hmap_path = NULL;

src/fios.h

@@ -92,15 +92,16 @@ enum FileSlots {
 	MAX_FILE_SLOTS = 64
 };
 
+/** Mode of the file dialogue window. */
 enum SaveLoadDialogMode {
-	SLD_LOAD_GAME,
+	SLD_LOAD_GAME,      ///< Load a game.
-	SLD_LOAD_SCENARIO,
+	SLD_LOAD_SCENARIO,  ///< Load a scenario.
-	SLD_SAVE_GAME,
+	SLD_SAVE_GAME,      ///< Save a game.
-	SLD_SAVE_SCENARIO,
+	SLD_SAVE_SCENARIO,  ///< Save a scenario.
-	SLD_LOAD_HEIGHTMAP,
+	SLD_LOAD_HEIGHTMAP, ///< Load a heightmap.
 };
 
-/* The different types of files been handled by the system */
+/** The different types of files that the system knows about. */
 enum FileType {
 	FT_NONE,      ///< nothing to do
 	FT_SAVEGAME,  ///< old or new savegame
@@ -122,7 +123,7 @@ enum FiosType {
 	FIOS_TYPE_INVALID = 255,
 };
 
-/* Deals with finding savegames */
+/** Deals with finding savegames */
 struct FiosItem {
 	FiosType type;
 	uint64 mtime;
@@ -130,7 +131,7 @@ struct FiosItem {
 	char name[MAX_PATH];
 };
 
-/* Deals with the type of the savegame, independent of extension */
+/** Deals with the type of the savegame, independent of extension */
 struct SmallFiosItem {
 	int mode;             ///< savegame/scenario type (old, new)
 	FileType filetype;    ///< what type of file are we dealing with
@@ -152,31 +153,23 @@ extern SmallFiosItem _file_to_saveload;
 extern SaveLoadDialogMode _saveload_mode;
 extern SortingBits _savegame_sort_order;
 
-/* Launch save/load dialog */
 void ShowSaveLoadDialog(SaveLoadDialogMode mode);
 
-/* Get a list of savegames */
 void FiosGetSavegameList(SaveLoadDialogMode mode);
-/* Get a list of scenarios */
 void FiosGetScenarioList(SaveLoadDialogMode mode);
-/* Get a list of Heightmaps */
 void FiosGetHeightmapList(SaveLoadDialogMode mode);
-/* Free the list of savegames */
+
 void FiosFreeSavegameList();
-/* Browse to. Returns a filename w/path if we reached a file. */
 const char *FiosBrowseTo(const FiosItem *item);
-/* Return path, free space and stringID */
+
 StringID FiosGetDescText(const char **path, uint64 *total_free);
-/* Delete a name */
 bool FiosDelete(const char *name);
-/* Make a filename from a name */
 void FiosMakeSavegameName(char *buf, const char *name, size_t size);
-/* Determines type of savegame (or tells it is not a savegame) */
+
 FiosType FiosGetSavegameListCallback(SaveLoadDialogMode mode, const char *file, const char *ext, char *title, const char *last);
 
 int CDECL CompareFiosItems(const FiosItem *a, const FiosItem *b);
 
-/* FIOS_TYPE_FILE, FIOS_TYPE_OLDFILE etc. different colours */
 extern const TextColour _fios_colours[];
 
 void BuildFileList();

src/fios_gui.cpp

@@ -191,7 +191,7 @@ static const NWidgetPart _nested_save_dialog_widgets[] = {
 	EndContainer(),
 };
 
-/* Colours for fios types */
+/** Colours for fios types, indexed by #FiosType. */
 const TextColour _fios_colours[] = {
 	TC_LIGHT_BLUE, TC_DARK_GREEN,  TC_DARK_GREEN, TC_ORANGE, TC_LIGHT_BROWN,
 	TC_ORANGE,     TC_LIGHT_BROWN, TC_ORANGE,     TC_ORANGE, TC_YELLOW
@@ -733,6 +733,10 @@ static const FileType _file_modetotype[] = {
 	FT_HEIGHTMAP, ///< used for SLD_LOAD_HEIGHTMAP
 };
 
+/**
+ * Launch save/load dialog in the given mode.
+ * @param mode Save/load mode.
+ */
 void ShowSaveLoadDialog(SaveLoadDialogMode mode)
 {
 	DeleteWindowById(WC_SAVELOAD, 0);