From 604e56adc2092d31c02f16b8412d550f7986557c Mon Sep 17 00:00:00 2001
From: alberth <alberth@openttd.org>
Date: Sun, 27 Jun 2010 09:05:10 +0000
Subject: [PATCH] (svn r20025) -Doc: Fix/add comments to let Doxygen know about
the documentation.
---
src/fios.cpp | 8 +++++---
src/network/network_gui.cpp | 6 ++++--
src/saveload/saveload.h | 14 ++++++++++----
src/string.cpp | 6 ++++--
src/vehicle.cpp | 3 ++-
5 files changed, 25 insertions(+), 12 deletions(-)
diff --git a/src/fios.cpp b/src/fios.cpp
index 398c7c7e3c..e1badddf37 100644
--- a/src/fios.cpp
+++ b/src/fios.cpp
@@ -84,9 +84,11 @@ StringID FiosGetDescText(const char **path, uint64 *total_free)
return FiosGetDiskFreeSpace(*path, total_free) ? STR_SAVELOAD_BYTES_FREE : STR_ERROR_UNABLE_TO_READ_DRIVE;
}
-/* Browse to a new path based on the passed FiosItem struct
- * @param *item FiosItem object telling us what to do
- * @return a string if we have given a file as a target, otherwise NULL */
+/**
+ * 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.
+ */
const char *FiosBrowseTo(const FiosItem *item)
{
char *path = _fios_path;
diff --git a/src/network/network_gui.cpp b/src/network/network_gui.cpp
index 6172e16438..95e98f2852 100644
--- a/src/network/network_gui.cpp
+++ b/src/network/network_gui.cpp
@@ -1718,8 +1718,10 @@ static const WindowDesc _network_lobby_window_desc(
_nested_network_lobby_window_widgets, lengthof(_nested_network_lobby_window_widgets)
);
-/* Show the networklobbywindow with the selected server
- * @param ngl Selected game pointer which is passed to the new window */
+/**
+ * Show the networklobbywindow with the selected server.
+ * @param ngl Selected game pointer which is passed to the new window.
+ */
static void ShowNetworkLobbyWindow(NetworkGameList *ngl)
{
DeleteWindowById(WC_NETWORK_WINDOW, 0);
diff --git a/src/saveload/saveload.h b/src/saveload/saveload.h
index b2a904106e..d3cb32dfc1 100644
--- a/src/saveload/saveload.h
+++ b/src/saveload/saveload.h
@@ -20,6 +20,7 @@
#define SIZE_MAX ((size_t)-1)
+/** Save or load result codes. */
enum SaveOrLoadResult {
SL_OK = 0, ///< completed successfully
SL_ERROR = 1, ///< error that was caught before internal structures were modified
@@ -36,6 +37,7 @@ enum SaveOrLoadMode {
SL_LOAD_CHECK = 5,
};
+/** Types of save games. */
enum SavegameType {
SGT_TTD, ///< TTD savegame (can be detected incorrectly)
SGT_TTDP1, ///< TTDP savegame ( -//- ) (data at NW border)
@@ -276,19 +278,23 @@ static inline bool SlIsObjectCurrentlyValid(uint16 version_from, uint16 version_
return true;
}
-/* Get the NumberType of a setting. This describes the integer type
+/**
+ * Get the NumberType of a setting. This describes the integer type
* as it is represented in memory
* @param type VarType holding information about the variable-type
- * @return return the SLE_VAR_* part of a variable-type description */
+ * @return return the SLE_VAR_* part of a variable-type description
+ */
static inline VarType GetVarMemType(VarType type)
{
return type & 0xF0; // GB(type, 4, 4) << 4;
}
-/* 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 return the SLE_FILE_* part of a variable-type description */
+ * @param return the SLE_FILE_* part of a variable-type description
+ */
static inline VarType GetVarFileType(VarType type)
{
return type & 0xF; // GB(type, 0, 4);
diff --git a/src/string.cpp b/src/string.cpp
index 4ed2da1292..79bf72c2d8 100644
--- a/src/string.cpp
+++ b/src/string.cpp
@@ -300,7 +300,8 @@ char *md5sumToString(char *buf, const char *last, const uint8 md5sum[16])
/* UTF-8 handling routines */
-/* Decode and consume the next UTF-8 encoded character
+/**
+ * Decode and consume the next UTF-8 encoded character.
* @param c Buffer to place decoded character.
* @param s Character stream to retrieve character from.
* @return Number of characters in the sequence.
@@ -339,7 +340,8 @@ size_t Utf8Decode(WChar *c, const char *s)
}
-/* Encode a unicode character and place it in the buffer
+/**
+ * Encode a unicode character and place it in the buffer.
* @param buf Buffer to place character.
* @param c Unicode character to encode.
* @return Number of characters in the encoded sequence.
diff --git a/src/vehicle.cpp b/src/vehicle.cpp
index f4cd16f8bd..85ed74271d 100644
--- a/src/vehicle.cpp
+++ b/src/vehicle.cpp
@@ -410,7 +410,8 @@ static Vehicle *EnsureNoVehicleProcZ(Vehicle *v, void *data)
return v;
}
-/* Ensure there is no vehicle at the ground at the given position.
+/**
+ * Ensure there is no vehicle at the ground at the given position.
* @param tile Position to examine.
* @return Succeeded command (ground is free) or failed command (a vehicle is found).
*/