@deftp {Data Type} struct po_xerror_handler
Its pointer is defined as @code{po_xerror_handler_t}. Contains
-two fields, xerror and xerror2, with the following function ignatures.
+two fields, @code{xerror} and @code{xerror2}, with the following function
+signatures.
@end deftp
@deftypefun void xerror (int@tie{}@var{severity}, po_message_t@tie{}@var{message}, const@tie{}char@tie{}*@var{filename}, size_t@tie{}@var{lineno}, size_t@tie{}@var{column}, int@tie{}@var{multiline_p}, const@tie{}char@tie{}*@var{message_text})
This function is called to signal a problem of the given @var{severity}.
It @emph{must not return} if @var{severity} is
-@var{PO_SEVERITY_FATAL_ERROR}.
+@code{PO_SEVERITY_FATAL_ERROR}.
@var{message_text} is the problem description. When @var{multiline_p}
is true, it can contain multiple lines of text, each terminated with a
This function is called to signal a problem of the given @var{severity}
that refers to two messages. It @emph{must not return} if
-@var{severity} is @var{PO_SEVERITY_FATAL_ERROR}.
+@var{severity} is @code{PO_SEVERITY_FATAL_ERROR}.
It is similar to two calls to xerror. If possible, an ellipsis can be
appended to @var{message_text1} and prepended to @var{message_text2}.
@end deftp
@deftypefun po_file_t po_file_create ()
-The @code{po_file_create} creates an empty PO file representation in
+The @code{po_file_create} function creates an empty PO file representation in
memory.
@end deftypefun
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
+This function is exported as @samp{po_file_read_v3} at ABI level, but is
defined as @code{po_file_read} in C code after the inclusion of
@samp{<gettext-po.h>}.
@end deftypefun
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
+is defined as @code{po_file_write} in C code after the inclusion of
@samp{<gettext-po.h>}.
@end deftypefun
@end deftp
@deftypefun {po_message_t} po_message_create (void)
-Return a freshly constructed message. To finish initializing the
-message, you must set the msgid and msgstr. It @emph{must} be inserted
-into a file to manage its memory, as there is no @code{po_message_free}
-available to the user of the library.
+Returns a freshly constructed message. To finish initializing the
+message, you must set the @code{msgid} and @code{msgstr}. It @emph{must} be
+inserted into a file to manage its memory, as there is no
+@code{po_message_free} available to the user of the library.
@end deftypefun
The following functions access details of a @code{po_message_t}. Recall
@deftypefun {const char *} po_message_msgctxt (po_message_t@tie{}@var{message})
The @code{po_message_msgctxt} function returns the @code{msgctxt}, the
-context of @var{message}. Return @code{NULL} for a message not restricted
+context of @var{message}. Returns @code{NULL} for a message not restricted
to a context.
@end deftypefun
@deftypefun {void} po_message_set_msgctxt (po_message_t@tie{}@var{message}, const@tie{}char@tie{}*@var{msgctxt})
The @code{po_message_set_msgctxt} function changes the @code{msgctxt},
the context of the message, to the value provided through
-@var{msgctxt}. The value @code{NULL} removes the restriction.
+@var{msgctxt}. The value @code{NULL} removes the restriction.
@end deftypefun
@deftypefun {const char *} po_message_msgid (po_message_t@tie{}@var{message})
@deftypefun {int} po_message_is_range (po_message_t@tie{}@var{message}, int@tie{}*@var{minp}, int@tie{}*@var{maxp})
The @code{po_message_is_range} function returns true when the message
has a numeric range set, and stores the minimum and maximum value in the
-direction pointed by @var{minp} and @var{maxp} respectively.
+locations pointed by @var{minp} and @var{maxp} respectively.
@end deftypefun
@deftypefun {void} po_message_set_range (po_message_t@tie{}@var{message}, int@tie{}@var{min}, int@tie{}@var{max})
The @code{po_message_set_range} function changes the numeric range of
the message. @var{min} and @var{max} must be non-negative, with
@var{min} < @var{max}. Use @var{min} and @var{max} with value @code{-1}
-to remove the numeric range of @var{message}
+to remove the numeric range of @var{message}.
@end deftypefun
@node PO Header Entry API
The following functions provide an interface to extract and manipulate
the header entry (@pxref{Header Entry}) from a file loaded in memory.
The meta information must be written back into the domain message with
-the empty string as msgid.
+the empty string as @code{msgid}.
@deftypefun {const char *} po_file_domain_header (po_file_t@tie{}@var{file}, const@tie{}char@tie{}*@var{domain})
-Return the header entry of a domain from @var{file}, a PO file loaded in
+Returns the header entry of a domain from @var{file}, a PO file loaded in
memory. The value @code{NULL} provided as @var{domain} denotes the
-default domain. Return @code{NULL} if there is no header entry.
+default domain. Returns @code{NULL} if there is no header entry.
@end deftypefun
@deftypefun {char *} po_header_field (const@tie{}char@tie{}*@var{header}, const@tie{}char@tie{}*@var{field})
-Return the value of @var{field} in the @var{header} entry. The return
+Returns the value of @var{field} in the @var{header} entry. The return
value is either a freshly allocated string, to be freed by the caller,
or @code{NULL}.
@end deftypefun
@deftypefun {char *} po_header_set_field (const@tie{}char@tie{}*@var{header}, const@tie{}char@tie{}*@var{field}, const@tie{}char@tie{}*@var{value})
-Return a freshly allocated string which contains the entry from
+Returns a freshly allocated string which contains the entry from
@var{header} with @var{field} set to @var{value}. The field is added if
necessary.
@end deftypefun
these references.
@deftypefun {po_filepos_t} po_message_filepos (po_message_t@tie{}@var{message}, int@tie{}@var{index})
-Return the file reference in position @var{index} from the message. If
-@var{index} is out of range, return @code{NULL}.
+Returns the file reference in position @var{index} from the message. If
+@var{index} is out of range, returns @code{NULL}.
@end deftypefun
@deftypefun {void} po_message_remove_filepos (po_message_t@tie{}@var{message}, int@tie{}@var{index})
-Remove the file reference in position @var{index} from the message. It
+Removes the file reference in position @var{index} from the message. It
moves all references following @var{index} one position backwards.
@end deftypefun
@deftypefun {void} po_message_add_filepos (po_message_t@tie{}@var{message}, const@tie{}char@tie{}*@var{file}, size_t@tie{}@var{start_line})
-Add a reference to the string from @var{file} starting at
+Adds a reference to the string from @var{file} starting at
@var{start_line}, if it is not already present for the message. The
value @code{(size_t)(-1)} for @var{start_line} denotes that the line
number is not available.
@subsection Format Type API
@deftypefun {const char * const *} po_format_list (void)
-Return a @code{NULL} terminated array of the supported format types.
+Returns a @code{NULL} terminated array of the supported format types.
@end deftypefun
@deftypefun {const char *} po_format_pretty_name (const@tie{}char@tie{}*@var{format_type})
-Return the pretty name associated with @var{format_type}. For example,
+Returns the pretty name associated with @var{format_type}. For example,
it returns ``C#'' when @var{format_type} is ``csharp_format''.
Return @code{NULL} if @var{format_type} is not a supported format type.
@end deftypefun
@subsection Checking API
@deftypefun {void} po_file_check_all (po_file_t@tie{}@var{file}, po_xerror_handler_t@tie{}@var{handler})
-Test whether the entire @var{file} is valid, like msgfmt does it. If it
-is invalid, pass the reasons to @var{handler}.
+Tests whether the entire @var{file} is valid, like @code{msgfmt} does it. If it
+is invalid, passes the reasons to @var{handler}.
@end deftypefun
@deftypefun {void} po_message_check_all (po_message_t@tie{}@var{message}, po_message_iterator_t@tie{}@var{iterator}, po_xerror_handler_t@tie{}@var{handler})
-Test @var{message}, to be inserted at @var{iterator} in a PO file in memory,
-like msgfmt does it. If it is invalid, pass the reasons to
+Tests @var{message}, to be inserted at @var{iterator} in a PO file in memory,
+like @code{msgfmt} does it. If it is invalid, passes the reasons to
@var{handler}. @var{iterator} is not modified by this call; it only
specifies the file and the domain.
@end deftypefun
@deftypefun {void} po_message_check_format (po_message_t@tie{}@var{message}, po_xerror_handler_t@tie{}@var{handler})
-Test whether the message translation from @var{message} is a valid
+Tests whether the message translation from @var{message} is a valid
format string if the message is marked as being a format string. If it
-is invalid, pass the reasons to @var{handler}.
+is invalid, passes the reasons to @var{handler}.
This function is exported as @samp{po_message_check_format_v2} at ABI
-level, but it defined as @code{po_message_check_format} in C code after
+level, but is defined as @code{po_message_check_format} in C code after
the inclusion of @samp{<gettext-po.h>}.
@end deftypefun
projects / thirdparty / gettext.git / commitdiff
