This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Merge branch 'ppport fixes' into blead
authorKarl Williamson <khw@cpan.org>
Tue, 3 Sep 2019 03:55:29 +0000 (21:55 -0600)
committerKarl Williamson <khw@cpan.org>
Tue, 3 Sep 2019 03:55:29 +0000 (21:55 -0600)
This branch contains a large number of changes related to the next
release of Devel::PPPort, which will regenerate its API list for the
first time in many years.

Documentation for 20-ish items is furnished, and the fact that some
dozens more are documented outside perlapi is now noted.

There is a new flag, h, to the =apidoc lines that indicates to hide the
documentation from perlapi, but tie it to the current place, like
perlapio.  It would be not too difficult to have such things
automagically pulled into perlapi from these, should that be desirable.

It turns out there were several undocumented conventions between D:P and
the core code, like having a parameter name of 'cast' or 'type' (in a
macro prototype apidoc line) that allowed D:P to generate proper code to
test the macro in the face of this parameter not being a legal C type.
I have documented these conventions, and added a couple more that the
next release of D:P will understand.  One of those is a parameter of
'block' as used in the recently added WITH_LC_NUMERIC_foo macros.  The
usage example in perlapi now displays correctly.

And for the few macros that I didn't add a way to test in D:P, there is
a new flag, 'u' to indicate that they are unorthodox or unconventional
in some way; that is they won't compile as-is.  This is applied, for
example, to the STR_WITH_LEN() macro which returns a comma separated
pair.

One thing that I hadn't realized before is that moving a function to
mathoms when there is no macro allowing it to be bypassed is effectively
deprecating the use of that function.  mathoms can be cleaned out at any
time, and installations may Configure to not even compile it.  I changed
to require the deprecated flag if something is in mathoms with no macro.

In an earlier commit, I had added the M flag as opposed to the m flag,
which previously had done double duty: 1) the function was implemented
only via a macro; 2) the function is a real function, but there is an
(extra) macro that you can use to get the same functionality as the
function.  I did this to help downstream processing.  And it turns out
that D:P needs that too, and needs it for functions in mathoms.  There
really is no need for an m flag with the mathoms (b) flag.  So the
existing ones that have an extra macro to bypass them are changed to use
the M flag instead of m.  This was done in an earlier commit for other
functions in this file.


Trivial merge