diff --git a/lib/uninorm.in.h b/lib/uninorm.in.h
index c9b1dd3..c5d4cf2 100644
--- a/lib/uninorm.in.h
+++ b/lib/uninorm.in.h
@@ -140,7 +140,20 @@ extern uninorm_t
        _UC_ATTRIBUTE_PURE;
 
 
-/* Return the specified normalization form of a string.  */
+/* Return the specified normalization form of a string. 
+ * This function operates in two modes:
+ *  - If (resultbuf) is provided, *lengthp should point to the maximum available size,
+ *    it will be updated to contain the string size in bytes.
+ *  - If (resultbuf) is NULL, the output buffer will be allocated using malloc(),
+ *    and *lengthp will contain the string size in bytes.
+ *
+ * In both cases, the output does not contain a NULL terminator. If (n) is zero
+ * and (resultbuf) is NULL, the function's return value is an allocated value
+ * with undefined contents.
+ *
+ * Returns the allocated with malloc() string, or a pointer to the provided (resultbuf),
+ * depending on the mode. On failure returns NULL.
+ */
 extern uint8_t *
        u8_normalize (uninorm_t nf, const uint8_t *s, size_t n,
                      uint8_t *resultbuf, size_t *lengthp);