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 ccf21d88ef8e0a3af93707464428b232fbbcb426..c7660b4e09fd3609711510a358197444374cd6ca 100644 (file)
--- 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 4f394eeeff356f3809fa2d9d2a8c35bf382b426f..62d413c665bf5fc3552888783cace75eb2506b01 100644 (file)
--- 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);