ialloc: Add comments

[Bruno Haible]

For the string-desc module, I need to make use of the 'ialloc' module.
Which is hard if its functions are not documented. I mean, as a user
of imalloc(), I'm not supposed to look into the module description
in order to understand that this function returns non-NULL for a
zero-sized allocation. Things like that should be stated as comments.

Done as follows:


2023-03-27  Bruno Haible  <bruno@clisp.org>

        ialloc: Add comments.
        * lib/ialloc.h (imalloc, irealloc, icalloc, ireallocarray): Add
        comments.

diff --git a/lib/ialloc.h b/lib/ialloc.h
index 1d43faf388..275237ccb1 100644
--- a/lib/ialloc.h
+++ b/lib/ialloc.h
@@ -43,6 +43,9 @@ _gl_alloc_nomem (void)
   return NULL;
 }
 
+/* imalloc (size) is like malloc (size).
+   It returns a non-NULL pointer to size bytes of memory.
+   Upon failure, it returns NULL with errno set.  */
 IALLOC_INLINE
 _GL_ATTRIBUTE_MALLOC /*_GL_ATTRIBUTE_DEALLOC_FREE*/
 void *
@@ -51,6 +54,9 @@ imalloc (idx_t s)
   return s <= SIZE_MAX ? malloc (s) : _gl_alloc_nomem ();
 }
 
+/* irealloc (ptr, size) is like realloc (ptr, size).
+   It returns a non-NULL pointer to size bytes of memory.
+   Upon failure, it returns NULL with errno set.  */
 IALLOC_INLINE
 /*_GL_ATTRIBUTE_DEALLOC_FREE*/
 void *
@@ -61,6 +67,9 @@ irealloc (void *p, idx_t s)
   return s <= SIZE_MAX ? realloc (p, s | !s) : _gl_alloc_nomem ();
 }
 
+/* icalloc (num, size) is like calloc (num, size).
+   It returns a non-NULL pointer to num * size bytes of memory.
+   Upon failure, it returns NULL with errno set.  */
 IALLOC_INLINE
 _GL_ATTRIBUTE_MALLOC /*_GL_ATTRIBUTE_DEALLOC_FREE*/
 void *
@@ -81,6 +90,9 @@ icalloc (idx_t n, idx_t s)
   return calloc (n, s);
 }
 
+/* ireallocarray (ptr, num, size) is like reallocarray (ptr, num, size).
+   It returns a non-NULL pointer to num * size bytes of memory.
+   Upon failure, it returns NULL with errno set.  */
 IALLOC_INLINE void *
 ireallocarray (void *p, idx_t n, idx_t s)
 {