[bug-libunistring] [PATCH] various updates and fixes to documentation

[Pádraig Brady]

---
 ChangeLog        | 11 ++++++++++-
 doc/unicase.texi |  7 +++++--
 doc/uninorm.texi |  6 ++++++
 doc/unistr.texi  |  3 +++
 4 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 5ceafec..b633edd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2019-02-23  Pádraig Brady <address@hidden>
+
+       Documentation updates/fixes.
+       * doc/unicase.texi: Fix types and mention why one might
+       use the _casecmp() variants over the _casecoll() ones.
+       * doc/uninorm.texi: Fully describe the parameters for
+       the _normalize() functions.
+       * doc/unistr.texi: Mention why one might use the _strcmp()
+       variants over the _strcoll() ones.
+
 2019-02-13  Bruno Haible  <address@hidden>
 
        doc: Assume that the texinfo sources are in the source dir.
@@ -564,7 +574,6 @@
        Avoid possible bad interaction with Solaris 2.5.1 <pthread.h>.
        * lib/stdint.mini.h (_UINT64_T): Don't define.
        Reported by Ben Pfaff <address@hidden>.
-
 2010-05-16  Bruno Haible  <address@hidden>
 
        Update after gnulib changed.
diff --git a/doc/unicase.texi b/doc/unicase.texi
index de8442c..514fbcb 100644
--- a/doc/unicase.texi
+++ b/doc/unicase.texi
@@ -48,7 +48,7 @@ The titlecase mapping of a character is to be used when the 
character should
 look like upper case and the following characters are lower cased.
 
 For most characters, this is the same as the uppercase mapping.  There are
-only few characters where the title case variant and the uuper case variant
+only a few characters where the title case variant and the upper case variant
 are different.  These characters occur in the Latin writing of the Croatian,
 Bosnian, and Serbian languages.
 
@@ -80,7 +80,7 @@ Bosnian, and Serbian languages.
 @cindex lowercasing
 @cindex titlecasing
 Case mapping should always be performed on entire strings, not on individual
-characters.  The functions in this sections do so.
+characters.  The functions in these sections do so.
 
 These functions allow to apply a normalization after the case mapping.  The
 reason is that if you want to treat @samp{@"{a}} and @samp{@"{A}} the same,
@@ -287,6 +287,9 @@ chapter @ref{Conventions}.
 @deftypefunx int u32_casecmp (address@hidden@address@hidden, 
address@hidden@var{n1}, address@hidden@address@hidden, address@hidden@var{n2}, 
address@hidden@address@hidden, address@hidden@var{nf}, 
address@hidden@var{resultp})
 @deftypefunx int ulc_casecmp (address@hidden@address@hidden, 
address@hidden@var{n1}, address@hidden@address@hidden, address@hidden@var{n2}, 
address@hidden@address@hidden, address@hidden@var{nf}, 
address@hidden@var{resultp})
 Compares @var{s1} and @var{s2}, ignoring differences in case and normalization.
+Use these rather than the @code{casecoll} variants below when you don't want 
the
+collation rules of the locale to be significant, or if you just want to test
+equality of two strings.
 
 The @var{nf} argument identifies the normalization form to apply after the
 case-mapping.  It can also be NULL, for no normalization.
diff --git a/doc/uninorm.texi b/doc/uninorm.texi
index f3a6574..97b1680 100644
--- a/doc/uninorm.texi
+++ b/doc/uninorm.texi
@@ -212,6 +212,12 @@ Returns the specified normalization form of a string.
 
 The @var{resultbuf} and @var{lengthp} arguments are as described in
 chapter @ref{Conventions}.
+
+If successful: The resulting Unicode string (non-NULL) is returned and
+its length stored in @address@hidden
+
+In case of error: NULL is returned and @code{errno} is set.
+Particular @code{errno} values: @code{EINVAL}, @code{EILSEQ}, @code{ENOMEM}.
 @end deftypefun
 
 @node Normalizing comparisons
diff --git a/doc/unistr.texi b/doc/unistr.texi
index c59094d..3bfd3ca 100644
--- a/doc/unistr.texi
+++ b/doc/unistr.texi
@@ -437,6 +437,9 @@ Compares @var{s1} and @var{s2}, lexicographically.
 Returns a negative value if @var{s1} compares smaller than @var{s2},
 a positive value if @var{s1} compares larger than @var{s2}, or 0 if
 they compare equal.
+Use these rather than the @code{strcoll} variants below when you don't want the
+collation rules of the locale to be significant, or if you just want to test
+equality of two strings.
 
 This function is similar to @posixfunc{strcmp} and @posixfunc{wcscmp}, except
 that it operates on Unicode strings.
-- 
2.9.3