Document several warner() fcns

2 files changed, 64 insertions, 15 deletions

diff --git a/embed.fnc b/embed.fnc
index 4101fdd724..172882cafa 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -698,7 +698,7 @@ AdfTp	|char*	|form_nocontext	|NN const char* pat|...
 AdFTp	|void	|load_module_nocontext|U32 flags|NN SV* name|NULLOK SV* ver|...
 AdfTp	|SV*	|mess_nocontext	|NN const char* pat|...
 AdfTp	|void	|warn_nocontext	|NN const char* pat|...
-AfTp	|void	|warner_nocontext|U32 err|NN const char* pat|...
+AdfTp	|void	|warner_nocontext|U32 err|NN const char* pat|...
 AdfTp	|SV*	|newSVpvf_nocontext|NN const char *const pat|...
 AdfTp	|void	|sv_catpvf_nocontext|NN SV *const sv|NN const char *const pat|...
 AdfTp	|void	|sv_setpvf_nocontext|NN SV *const sv|NN const char *const pat|...
@@ -2591,10 +2591,10 @@ p	|void	|report_redefined_cv|NN const SV *name \
 Apd	|void	|warn_sv	|NN SV *baseex
 Afpd	|void	|warn		|NN const char* pat|...
 Apd	|void	|vwarn		|NN const char* pat|NULLOK va_list* args
-Afp	|void	|warner		|U32 err|NN const char* pat|...
-Afp	|void	|ck_warner	|U32 err|NN const char* pat|...
-Afp	|void	|ck_warner_d	|U32 err|NN const char* pat|...
-Ap	|void	|vwarner	|U32 err|NN const char* pat|NULLOK va_list* args
+Adfp	|void	|warner		|U32 err|NN const char* pat|...
+Adfp	|void	|ck_warner	|U32 err|NN const char* pat|...
+Adfp	|void	|ck_warner_d	|U32 err|NN const char* pat|...
+Adp	|void	|vwarner	|U32 err|NN const char* pat|NULLOK va_list* args
 #ifdef USE_C_BACKTRACE
 pd	|Perl_c_backtrace*|get_c_backtrace|int max_depth|int skip
 dm	|void	|free_c_backtrace|NN Perl_c_backtrace* bt
diff --git a/util.c b/util.c
index 401b0cf9fd..18ef553867 100644
--- a/util.c
+++ b/util.c
@@ -2006,23 +2006,23 @@ Perl_vwarn(pTHX_ const char* pat, va_list *args)
 
 /*
 =for apidoc warn
+=for apidoc_item warn_nocontext
 
-This is an XS interface to Perl's C<warn> function.
+These are XS interfaces to Perl's C<warn> function.
 
-Take a sprintf-style format pattern and argument list.  These are used to
-generate a string message.  If the message does not end with a newline,
-then it will be extended with some indication of the current location
-in the code, as described for L</mess_sv>.
+They take a sprintf-style format pattern and argument list, which  are used to
+generate a string message.  If the message does not end with a newline, then it
+will be extended with some indication of the current location in the code, as
+described for C<L</mess_sv>>.
 
 The error message or object will by default be written to standard error,
 but this is subject to modification by a C<$SIG{__WARN__}> handler.
 
-Unlike with L</croak>, C<pat> is not permitted to be null.
+Unlike with C<L</croak>>, C<pat> is not permitted to be null.
 
-=for apidoc warn_nocontext
-Like C<L</warn>> but does not take a thread context (C<aTHX>) parameter,
-so is used in situations where the caller doesn't already have the thread
-context.
+The two forms differ only in that C<warn_nocontext> does not take a thread
+context (C<aTHX>) parameter, so is used in situations where the caller doesn't
+already have the thread context.
 
 =cut
 */
@@ -2050,6 +2050,55 @@ Perl_warn(pTHX_ const char *pat, ...)
     va_end(args);
 }
 
+/*
+=for apidoc warner
+=for apidoc_item warner_nocontext
+
+These output a warning of the specified category (or categories) given by
+C<err>, using the sprintf-style format pattern C<pat>, and argument list.
+
+C<err> must be one of the C<L</packWARN>>, C<packWARN2>, C<packWARN3>,
+C<packWARN4> macros populated with the appropriate number of warning
+categories.  If any of the warning categories they specify is fatal, a fatal
+exception is thrown.
+
+In any event a message is generated by the pattern and arguments.  If the
+message does not end with a newline, then it will be extended with some
+indication of the current location in the code, as described for L</mess_sv>.
+
+The error message or object will by default be written to standard error,
+but this is subject to modification by a C<$SIG{__WARN__}> handler.
+
+C<pat> is not permitted to be null.
+
+The two forms differ only in that C<warner_nocontext> does not take a thread
+context (C<aTHX>) parameter, so is used in situations where the caller doesn't
+already have the thread context.
+
+These functions differ from the similarly named C<L</warn>> functions, in that
+the latter are for XS code to unconditionally display a warning, whereas these
+are for code that may be compiling a perl program, and does extra checking to
+see if the warning should be fatal.
+
+=for apidoc ck_warner
+=for apidoc_item ck_warner_d
+If none of the warning categories given by C<err> are enabled, do nothing;
+otherwise call C<L</warner>>  or C<L</warner_nocontext>> with the passed-in
+parameters;.
+
+C<err> must be one of the C<L</packWARN>>, C<packWARN2>, C<packWARN3>,
+C<packWARN4> macros populated with the appropriate number of warning
+categories.
+
+The two forms differ only in that C<ck_warner_d> should be used if warnings for
+any of the categories are by default enabled.
+
+=for apidoc vwarner
+This is like C<L</warner>>, but C<args> are an encapsulated argument list.
+
+=cut
+*/
+
 #if defined(PERL_IMPLICIT_CONTEXT)
 void
 Perl_warner_nocontext(U32 err, const char *pat, ...)