perlapi: Combine vwarner and similar with warner entry

This commit places all similar functions into the same entry, making it
easier for the reader to choose which is best for their needs.

Author: khwilliamson

autodoc.pl

@@ -96,7 +96,6 @@
                                     sv_setpvf
                                     sv_setpvf_mg
                                     warn
-                                    warner
                                   );
 my %has_compat_macro;
 $has_compat_macro{$_} = 1 for @have_compatibility_macros;

util.c

@@ -2049,18 +2049,30 @@ Perl_warn(pTHX_ const char *pat, ...)
 }
 
 /*
-=for apidoc warner
+=for apidoc      warner
 =for apidoc_item warner_nocontext
+=for apidoc_item vwarner
+=for apidoc_item fatal_warner
+=for apidoc_item vfatal_warner
 
 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>, using the sprintf-style format pattern C<pat>, and the arguments.
 
 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
+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
+C<fatal_warner> and C<vfatal_warner> act as if fatal warnings are enabled
+for the warning.  If called when there are pending compilation errors these
+functions may actually return.  They are currently used to generate "used only
+once" fatal warnings since the COP where the name being reported is no longer
+the current COP when the warning is generated and may be useful for similar
+cases.
+
+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>.
 
@@ -2069,13 +2081,18 @@ 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.
+The arguments to C<vwarner> and C<vfatal_warner> are specified as a
+C<va_list>.  The arguments to the remaining forms are specified as a
+sprintf-style list of arguments.
+
+C<warner> and C<warner_nocontext> behave identically when called from outside
+the perl core unless C<PERL_WANT_VARARGS> has been explicitly #defined.
+When it has, or when called from inside the core, they differ only in that
+C<warner> requires the thread context (C<aTHX>) to be available.
 
 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
+are for code that may be compiling a perl program, and do extra checking to
 see if the warning should be fatal.
 
 =for apidoc ck_warner
@@ -2091,29 +2108,6 @@ 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.
-
-=for apidoc fatal_warner
-
-Like L</warner> except that it acts as if fatal warnings are enabled
-for the warning.
-
-If called when there are pending compilation errors this function may
-return.
-
-This is currently used to generate "used only once" fatal warnings
-since the COP where the name being reported is no longer the current
-COP when the warning is generated and may be useful for similar cases.
-
-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.
-
-=for apidoc vfatal_warner
-
-This is like C<L</fatal_warner>> but C<args> are an encapsulated
-argument list.
 
 =cut
 */