From f5637b797540120201d98a23f7bb607550fda21b Mon Sep 17 00:00:00 2001 From: alberth Date: Fri, 27 May 2011 21:20:07 +0000 Subject: (svn r22500) -Doc: Fix and add fios doxygen documentation. --- src/fios.cpp | 25 ++++++++++++++++++------- src/fios.h | 31 ++++++++++++------------------- src/fios_gui.cpp | 6 +++++- 3 files changed, 35 insertions(+), 27 deletions(-) (limited to 'src') diff --git a/src/fios.cpp b/src/fios.cpp index 8dbb1fae8..37b530cbd 100644 --- a/src/fios.cpp +++ b/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. - * @param *item #FiosItem object telling us what to do. - * @return A string if we have given a file as a target, otherwise \c NULL. + * Browse to a new path based on the passed \a item, starting at #_fios_path. + * @param *item Item telling us what to do. + * @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; diff --git a/src/fios.h b/src/fios.h index 6abef9bb3..f666eb5bf 100644 --- a/src/fios.h +++ b/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_SCENARIO, - SLD_SAVE_GAME, - SLD_SAVE_SCENARIO, - SLD_LOAD_HEIGHTMAP, + SLD_LOAD_GAME, ///< Load a game. + SLD_LOAD_SCENARIO, ///< Load a scenario. + SLD_SAVE_GAME, ///< Save a game. + SLD_SAVE_SCENARIO, ///< Save a scenario. + 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(); diff --git a/src/fios_gui.cpp b/src/fios_gui.cpp index 8d1fb1b80..84d41755c 100644 --- a/src/fios_gui.cpp +++ b/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); -- cgit v1.2.3-54-g00ecf