more documentation.

[apps/madmutt.git] / lib-lib / str.h

diff --git a/lib-lib/str.h b/lib-lib/str.h
index 51eeba4..345c16c 100644 (file)
--- a/lib-lib/str.h
+++ b/lib-lib/str.h
@@ -24,12 +24,9 @@
 #ifndef MUTT_LIB_LIB_STR_H
 #define MUTT_LIB_LIB_STR_H
 
-/** \file str.h.
- * \brief Madmutt string API.
+/** \defgroup mutt_strings Madmutt string API
  *
- * \author Pierre Habouzit <madcoder@debian.org>
- *
- * This header contains the prefered string API to be used in Madmutt.
+ * This module contains the prefered string API to be used in Madmutt.
  *
  * Those function reimplement many usual calls (strlen, strcpy, strcat, …)
  * It's intended to provide a uniform and consistent API to deal with usual C
@@ -40,14 +37,19 @@
  *    stupid semantics à la strncpy.
  *  - function try to always work on buffers with its size (including the
  *    ending \c '\\0') to prevent buffer overflows.
- *  - string and buffers sizes are ssize_t, negative values are allowed and
+ *  - string and buffers sizes are \c ssize_t, negative values are allowed and
  *    supported.
  *  - functions use a à la sprintf semantics (for those that produce strings)
  *    meaning that they all return the len that could have fit in the buffer
  *    if it would have been big enough. We never try to reallocate the
  *    buffers, it's up to the caller if it's needed.
  */
+/*@{*/
 
+/** \file str.h
+ * \brief Madmutt string API header.
+ * \author Pierre Habouzit <madcoder@debian.org>
+ */
 
 #define HUGE_STRING     5120   /**< \brief Huge buffers */
 #define LONG_STRING     1024   /**< \brief Long buffers */
@@ -57,12 +59,30 @@
                                                   with emtpy strings */
 #define ISSPACE(c)      isspace((unsigned char)c) /**< \brief safe isspace */
 
-
+/** \brief Convert ascii digits into ints.
+ *
+ * Convert ascii digits into its integer value in base 36.
+ * Non convertible values are converted to 255.
+ *
+ * Translating a digit \c c into its numerical value in base \c x is just doing:
+ * \code
+ *   return (c & ~127) && __m_strdigits[c] < x ? __m_strdigits[c] : -1;
+ * \endcode
+ */
 extern unsigned char const __m_strdigits[128];
+/** \brief Convert an ascii base64 digit into ints.
+ *
+ * Convert an a char base64 digit into its int value.
+ * Used by base64val(). Unlike #__m_strdigits, the invalid values are set to
+ * -1 instead of 255.
+ */
 extern signed char const __m_b64digits[128];
-extern char const __m_b64chars[64];
 
+/** \brief Convert ints from 0&ndash;64 into the corresponding base64 digit. */
+extern char const __m_b64chars[64];
+/** \brief Convert ints from 0&ndash;36 into a base36 lowercase digit. */
 extern char const __m_b36chars_lower[36];
+/** \brief Convert ints from 0&ndash;36 into a base36 uppercase digit. */
 extern char const __m_b36chars_upper[36];
 
 /****************************************************************************/
@@ -162,8 +182,11 @@ static inline ssize_t m_strputc(char *dst, ssize_t n, int c) {
     return 1;
 }
 
-ssize_t m_strcpy(char *dst, ssize_t n, const char *src);
-ssize_t m_strncpy(char *dst, ssize_t n, const char *src, ssize_t l);
+ssize_t m_strcpy(char *dst, ssize_t n, const char *src)
+    __attribute__((nonnull(1)));
+
+ssize_t m_strncpy(char *dst, ssize_t n, const char *src, ssize_t l)
+    __attribute__((nonnull(1)));
 
 static inline ssize_t m_strcat(char *dst, ssize_t n, const char *src) {
     ssize_t dlen = m_strnlen(dst, n - 1);
@@ -201,7 +224,8 @@ static inline char *vskipspaces(const char *s) {
     return (char *)skipspaces(s);
 }
 
-char *m_strrtrim(char *s);
+char *m_strrtrim(char *s)
+    __attribute__((nonnull(1)));
 
 /****************************************************************************/
 /* search                                                                   */
@@ -215,4 +239,5 @@ m_stristr(const char *haystack, const char *needle) {
     return m_stristrn(haystack, needle, m_strlen(needle));
 }
 
+/*@}*/
 #endif /* MUTT_LIB_LIB_STR_H */