From: Miguel Ángel Arruga Vivas <rosen644835@gmail.com>
Date: Sun, 5 May 2019 17:54:44 +0000 (+0200)
Subject: doc: Update po_file_read documentation
X-Git-Tag: v0.21~23
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ceb9bd73aab65ff335cf85bf41e210f6c6ea1c8e;p=thirdparty%2Fgettext.git

doc: Update po_file_read documentation

* gettext-tools/doc/gettext.texi (libgettextpo): Update documentation
from po_file_read to the version 3 of the implementation.
* gettext-tools/libgettextpo/gettext-po.in.h (po_file_read): Update
comment.
---

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index bb18a3463..ccf21d88e 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -5402,11 +5402,16 @@ The @code{po_file_create} creates an empty PO file representation in
 memory.
 @end deftypefun
 
-@deftypefun po_file_t po_file_read (const char *@var{filename})
+@deftypefun po_file_t po_file_read (const char *@var{filename},@
+            struct po_xerror_handler *@var{handler})
 The @code{po_file_read} function reads a PO file into memory.  The file name
 is given as argument.  The return value is a handle to the PO file's contents,
-valid until @code{po_file_free} is called on it.  In case of error, the return
-value is @code{NULL}, and @code{errno} is set.
+valid until @code{po_file_free} is called on it.  In case of error, the
+functions from @var{handler} are called to signal it.
+
+This function is exported as @samp{po_file_read_v3} at ABI level, but it
+defined as @code{po_file_read} in C code after the inclusion of
+@samp{<gettext-po.h>}.
 @end deftypefun
 
 @deftypefun void po_file_free (po_file_t @var{file})
diff --git a/gettext-tools/libgettextpo/gettext-po.in.h b/gettext-tools/libgettextpo/gettext-po.in.h
index f6c1a8bf6..4f394eeef 100644
--- a/gettext-tools/libgettextpo/gettext-po.in.h
+++ b/gettext-tools/libgettextpo/gettext-po.in.h
@@ -131,7 +131,7 @@ typedef const struct po_xerror_handler *po_xerror_handler_t;
 extern po_file_t po_file_create (void);
 
 /* Read a PO file into memory.
-   Return its contents.  Upon failure, return NULL and set errno.  */
+   Return its contents.  Upon failure, call function from handler.  */
 #define po_file_read po_file_read_v3
 extern po_file_t po_file_read (const char *filename,
                                po_xerror_handler_t handler);