(svn r14553) -Doc: Add some doxygen comments

2 files changed, 44 insertions, 4 deletions

diff --git a/src/stdafx.h b/src/stdafx.h
index 5ca14d082..34da8f501 100644
--- a/src/stdafx.h
+++ b/src/stdafx.h
@@ -305,8 +305,30 @@ assert_compile(sizeof(uint32) == 4);
 assert_compile(sizeof(uint16) == 2);
 assert_compile(sizeof(uint8)  == 1);
 
+/**
+ * Return the length of an fixed size array.
+ * Unlike sizeof this function returns the number of elements
+ * of the given type.
+ *
+ * @param x The pointer to the first element of the array
+ * @return The number of elements
+ */
 #define lengthof(x) (sizeof(x) / sizeof(x[0]))
+
+/**
+ * Get the end element of an fixed size array.
+ *
+ * @param x The pointer to the first element of the array
+ * @return The pointer past to the last element of the array
+ */
 #define endof(x) (&x[lengthof(x)])
+
+/**
+ * Get the last element of an fixed size array.
+ *
+ * @param x The pointer to the first element of the array
+ * @return The pointer to the last element of the array
+ */
 #define lastof(x) (&x[lengthof(x) - 1])
 
 #define cpp_offsetof(s, m)   (((size_t)&reinterpret_cast<const volatile char&>((((s*)(char*)8)->m))) - 8)
diff --git a/src/string_func.h b/src/string_func.h
index 97834f456..04f752921 100644
--- a/src/string_func.h
+++ b/src/string_func.h
@@ -29,6 +29,7 @@
  * buffer.
  *
  * @note usage ttd_strlcat(dst, src, lengthof(dst));
+ * @note lengthof() applies only to fixed size arrays
  *
  * @param dst The buffer containing the target string
  * @param src The buffer containing the string to append
@@ -44,6 +45,7 @@ void ttd_strlcat(char *dst, const char *src, size_t size);
  * buffer.
  *
  * @note usage ttd_strlcpy(dst, src, lengthof(dst));
+ * @note lengthof() applies only to fixed size arrays
  *
  * @param dst The destination buffer
  * @param src The buffer containing the string to copy
@@ -60,6 +62,7 @@ void ttd_strlcpy(char *dst, const char *src, size_t size);
  * boundary check is performed.
  *
  * @note usage: strecat(dst, src, lastof(dst));
+ * @note lastof() applies only to fixed size arrays
  *
  * @param dst The buffer containing the target string
  * @param src The buffer containing the string to append
@@ -77,6 +80,7 @@ char *strecat(char *dst, const char *src, const char *last);
  * check is performed.
  *
  * @note usage: strecpy(dst, src, lastof(dst));
+ * @note lastof() applies only to fixed size arrays
  *
  * @param dst The destination buffer
  * @param src The buffer containing the string to copy
@@ -99,11 +103,25 @@ void str_strip_colours(char *str);
 /** Convert the given string to lowercase, only works with ASCII! */
 void strtolower(char *str);
 
+/**
+ * Check if a string buffer is empty.
+ *
+ * @param s The pointer to the firste element of the buffer
+ * @return true if the buffer starts with the terminating null-character or
+ *         if the given pointer points to NULL else return false
+ */
+static inline bool StrEmpty(const char *s)
+{
+	return s == NULL || s[0] == '\0';
+}
 
-static inline bool StrEmpty(const char *s) { return s == NULL || s[0] == '\0'; }
-
-
-/** Get the length of a string, within a limited buffer */
+/**
+ * Get the length of a string, within a limited buffer.
+ *
+ * @param str The pointer to the firste element of the buffer
+ * @param maxlen The maximum size of the buffer
+ * @return The length of the string
+ */
 static inline size_t ttd_strnlen(const char *str, size_t maxlen)
 {
 	const char *t;