Hi,
I have been trying to understand the normalize API, and in the
process I have written down some text for the function description. I
am not sure if my understanding of the API is right, but here is some
proposed documentation patch for u*_normalize().
The conventions [0] section seem to cover some of this text.
regards,
Nikos
[0].
https://www.gnu.org/software/libunistring/manual/libunistring.html#Conventions
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);
