perltodo - document diagnostics

Hello.

I'd like to start taking care of the 'document diagnostics' perltodo:

"Many diagnostic messages are not currently documented.  The list is at the
end
of t/porting/diag.t."

I noticed while starting to hack away at this test that it has a few minor
bugs, specifically

  - The regex for matching warning strings can be tripped up by stuff like:
      Perl_croak(aTHX_ "Can't open "BIT_BUCKET": %s\n", Strerror(errno));

    It reads that as "Can't open"

  - The test parser tries to match entries in perldiag.pod almost verbatim,
whereas splain attempts to match using printf format characters.

  - There are no extensive tests (that I've seen ) to make sure splain will
match warnings generated by Perl correctly to those in perldiag.pod

I'd like to fix these things and attempt to start documenting the various
strings in the todo as I have time. (A couple a week maybe)

To do that though, I was hoping I could get clarification on the following
point:

Is the purpose of perldiag.pod to both document what the user might see and
to utilize the printf-formatting characters to make a single =item entry for
a group of warnings like so:

 =item Argument "%s" isn't numeric%s

Or would it be more proper to document the different variations of the same
warning exactly as they might appear:

=item Argument "%s" isn't numeric

=item Argument "%s" isn't numeric in %s

The second form is more verbose in the documentation, but still allows the
printf formatting to match what it needs.

I would appreciate some input here.

Thanks,

-- Matthew Horsfall (alh)

• perltodo - document diagnostics by Matthew Horsfall
• Re: perltodo - document diagnostics by Matthew Horsfall
• Re: perltodo - document diagnostics by Karl Williamson