[doc] perlapi: documentation for croak_xs_usage has an undefined "diag_listed_as" tag in the example

[djerius]

Perl v5.40.0

Where

perlapi

Description

The documentation for croak_xs_usage reads in part

    works out the package name and subroutine name from "cv", and then
    calls croak(). Hence if "cv" is &ouch::awk, it would call "croak"
    as:

     diag_listed_as: SKIPME
     Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
                                                         "eee_yow");

The diag_listed_as: SKIPME tag is not defined anywhere that I could find.

[djerius]

There's also a comma missing between "ouch" and "awk".

[ilmari]

This is used by t/porting/diag.t:

    # Special syntax for magic comment, allows ignoring the fact
    # that it isn't listed.  Only use in very special circumstances,
    # like this script failing to notice that the Perl_croak call is
    # inside an #if 0 block.
    next if $name eq 'SKIPME';

[djerius]

Including it in the example confuses the reader. Examples should be reasonably cut'n'paste, and doing so with this example would not compile (apart from the C syntax error, which passes one fewer arguments than it should, and might cause a segv if the compiler didn't catch there were too few arguments)

[tonycoz]

diag_listed_as: xxxx is only recognised between * pairs or at end of line after a *, so this one would be ignored anyway.

The diag,t parser doesn't even report on this particular call, it gets confused by the C<croak> and gathers up to the end of the sample Perl_croak() call (quotemetad since that how I printed is in the debugger):

C\<croak\(\)\>\.\ \ Hence\ if\ C\<cv\>\ is\ C\<\&ouch\:\:awk\>\,\ it\ would\ call\ C\<croak\>\ as\:croak\(\"Usage\:\ \%s\:\:\%s\(\%s\)\"\,\ \"ouch\"\ \"awk\"\,\"eee_yow\"\)\;

and decides that isn't a function call and proceeds to ignore it.

Of course that's a different type of problem.

All tests pass if this is removed.

[djerius]

Thanks!