1 files changed, 19 insertions, 1 deletions
diff --git a/src/xine-utils/utils.c b/src/xine-utils/utils.c
index 48ceef688..4085d65ee 100644
--- a/src/xine-utils/utils.c
+++ b/src/xine-utils/utils.c
@@ -236,7 +236,25 @@ static const lang_locale_t lang_locales[] = {
   { NULL,       NULL,          NULL,          NULL       }
 };
 
-
+/**
+ * @brief Allocate and clean memory size_t 'size', then return the
+ *        pointer to the allocated memory.
+ * @param size Size of the memory area to allocate.
+ *
+ * @return A pointer to the allocated memory area, or NULL in case of
+ *         error.
+ *
+ * The behaviour of this function differs from standard malloc() as
+ * xine_xmalloc(0) will not return a NULL pointer, but rather a
+ * pointer to a memory area of size 1 byte.
+ *
+ * The NULL value is only ever returned in case of an error in
+ * malloc(), and is reported to stderr stream.
+ *
+ * @deprecated This function has been deprecated, as the behaviour of
+ *             allocating a 1 byte memory area on zero size is almost
+ *             never desired, and the function is thus mostly misused.
+ */
 void *xine_xmalloc(size_t size) {
   void *ptr;