From: Miguel Ángel Arruga Vivas <rosen644835@gmail.com>
Date: Sun, 5 May 2019 18:02:26 +0000 (+0200)
Subject: doc: Add po_file_write documentation
X-Git-Tag: v0.21~22
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=16cf82eb5c3d2b4b0b1b03464063fcfa2e995cfe;p=thirdparty%2Fgettext.git

doc: Add po_file_write documentation

* gettext-tools/doc/gettext.texi (libgettextpo): Add po_file_write
documentation.
* gettext-tools/doc/gettext-po.in.h (po_file_write): Update comment.
---

diff --git a/gettext-tools/doc/gettext.texi b/gettext-tools/doc/gettext.texi
index ccf21d88e..c7660b4e0 100644
--- a/gettext-tools/doc/gettext.texi
+++ b/gettext-tools/doc/gettext.texi
@@ -5325,7 +5325,8 @@ is not sufficient, a set of C functions is provided in a library, to make it
 possible to process PO files in your own programs.  When you use this library,
 you don't need to write routines to parse the PO file; instead, you retrieve
 a pointer in memory to each of messages contained in the PO file.  Functions
-for writing PO files are not provided at this time.
+for writing those memory structures to a file after working with them are
+provided too.
 
 The functions are declared in the header file @samp{<gettext-po.h>}, and are
 defined in a library called @samp{libgettextpo}.
@@ -5414,6 +5415,18 @@ defined as @code{po_file_read} in C code after the inclusion of
 @samp{<gettext-po.h>}.
 @end deftypefun
 
+@deftypefun po_file_t po_file_write (po_file_t @var{file},@
+            const char *@var{filename}, struct po_xerror_handler *@var{handler})
+The @code{po_file_write} function writes the contents of the memory
+structure @var{file} the @var{filename} given.  The return value is
+@var{file} after a successful operation.  In case of error, the
+functions from @var{handler} are called to signal it.
+
+This function is exported as @samp{po_file_write_v2} at ABI level, but
+it defined as @code{po_file_write} in C code after the inclusion of
+@samp{<gettext-po.h>}.
+@end deftypefun
+
 @deftypefun void po_file_free (po_file_t @var{file})
 The @code{po_file_free} function frees a PO file's contents from memory,
 including all messages that are only implicitly accessible through iterators.
diff --git a/gettext-tools/libgettextpo/gettext-po.in.h b/gettext-tools/libgettextpo/gettext-po.in.h
index 4f394eeef..62d413c66 100644
--- a/gettext-tools/libgettextpo/gettext-po.in.h
+++ b/gettext-tools/libgettextpo/gettext-po.in.h
@@ -137,7 +137,7 @@ extern po_file_t po_file_read (const char *filename,
                                po_xerror_handler_t handler);
 
 /* Write an in-memory PO file to a file.
-   Upon failure, return NULL and set errno.  */
+   Upon failure, call function from handler.  */
 #define po_file_write po_file_write_v2
 extern po_file_t po_file_write (po_file_t file, const char *filename,
                                 po_xerror_handler_t handler);