no more SHORT_STRING's. begin some doc.

Signed-off-by: Pierre Habouzit <madcoder@debian.org>

diff --git a/lib-lib/str.h b/lib-lib/str.h
index e456fdd..51eeba4 100644 (file)
--- a/lib-lib/str.h
+++ b/lib-lib/str.h
@@ -24,13 +24,39 @@
 #ifndef MUTT_LIB_LIB_STR_H
 #define MUTT_LIB_LIB_STR_H
 
-#define HUGE_STRING     5120
-#define LONG_STRING     1024
-#define STRING          256
-#define SHORT_STRING    128
+/** \file str.h.
+ * \brief Madmutt string API.
+ *
+ * \author Pierre Habouzit <madcoder@debian.org>
+ *
+ * This header 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
+ * strings.
+ *
+ * The strong point that have to be followed are:
+ *  - strings are always \c '\\0' terminated, meaning that we don't have
+ *    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
+ *    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.
+ */
+
+
+#define HUGE_STRING     5120   /**< \brief Huge buffers */
+#define LONG_STRING     1024   /**< \brief Long buffers */
+#define STRING          256    /**< \brief Usual buffers */
+
+#define NONULL(x)       (x ? x : "")  /**< \brief replace \c NULL strings
+                                                  with emtpy strings */
+#define ISSPACE(c)      isspace((unsigned char)c) /**< \brief safe isspace */
 
-#define NONULL(x)       (x?x:"")
-#define ISSPACE(c)      isspace((unsigned char)c)
 
 extern unsigned char const __m_strdigits[128];
 extern signed char const __m_b64digits[128];