This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Merge branch 'autodoc' into blead
authorKarl Williamson <khw@cpan.org>
Fri, 31 May 2019 00:14:00 +0000 (18:14 -0600)
committerKarl Williamson <khw@cpan.org>
Fri, 31 May 2019 00:14:00 +0000 (18:14 -0600)
commit21af3a52053bc3558259ca470f5501197e0e75c6
treeebce5a5de1074d5c0716062d59086826cd3165cd
parentda5a0da22ef5f5dd64e1fcdcac2c5ed1c0398085
parent790ba7215e8e4fa4c6a0c0684565f40c31afd885
Merge branch 'autodoc' into blead

This branch cleans up a bunch of the autodoc handling.

It had its genesis in an obscure warning from Devel::PPPort:

    mysterious name

It turns out that the pod entry for the macros the warnings are for are
improper.  My guess is that it was a kludge by someone looking for a
quick way to get their usage point across, when the underlying
infrastructure was deficient in allowing it.  But it looked to be fairly
easy to enhance that infrastructure.

But then I noticed that some of the flags in the embed.fnc entries have
different meanings than the equivalent =for apidoc entries in the
source.

Here are most of the conflicts:
Flag embed.fnc =for apidoc
n no pTHX don't output empty parens for no arguments
s S_ static fcn output a semi-colon at the end of the usage entry
x Don't export experimental

I imagine that they started out the same, and diverged over the years,
as there was no unified place where they were documented.  Devel::PPPort
was unaware of this divergence, and so got some things wrong, and had
some code expecting one flag, and other code expecting the other.

This branch changes the flags in embed.fnc to correspond with what
autdoc wants, and brings everything else that uses them into
conformance.  embed.fnc is a more contained place to change, and I
couldn't find anything in CPAN that would be bothered by this.  And
also, if D:P were to be regenerated on an older perl, it still would use
the new embed.fnc shipped with it, but would be using the flags from the
older perl source code, so it had to be embed.fnc that changed.

The O flag in embed.fnc can then be used instead of having another flag
in the =for apidoc entries for the situation of having deprecated
'perl_' prefixes, removing the need for autodoc to have to try to figure
it out, and there were places where it had been getting it wrong.

Once that was done, the flags in embed.fnc could override the ones in
the =for api entries, as every flag has the same meaning in both places.
Doing so showed a bunch of errors, mostly missing 'const's in the
parameters, but, besides the 'perl_' prefix errors, some functions were
not listed as needing to be called with the 'Perl_' prefix.  The flags
in embed.fnc have to be pretty accurate, or perl won't compile.

I then removed about 150 redundant =for apidoc entries.  It is a waste
having them in the code twice, and they do get out of sync.  Note that
there does need to be an entry like

    =for apidoc FOO

for the autodoc facility to know where the actual pod for a given
function is.  And the entry needs to have the flags, return value, and
argument list detailed if and only if FOO isn't in embed.fnc.  I myself
didn't know that if omitted, the values in embed.fnc were used, so I
wasted time in the past duplicating these.  Now, if there's duplication
autodoc will warn.

autodoc did check for a couple of discrepancies if there were two
entries, but that code is now unnecessary and has been ripped out.

I added a flag so that something that isn't a straight name can be
documented, and will rip out the code in D:P that special-cased the few
existing entries that were like this.  Now there is a warning from
autodoc, unless the flag is present, when this happens, so that
'mysterious name' won't show up again.

I added another flag to make it easier to deal with functions that have
become wrappers for others, and there is a macro that bypasses the
original one, but for back compat, we still have the original.

autodoc did not realize that you could have things like
Perl_sprintf_nocontext() without a pTHX.  That flag already is in
embed.fnc, and now autodoc uses it.

Finally, I added extensive comments to embed.fnc to document all the
flags, and removed other outdated comments elsewhere in favor of a
pointer to the comments in embed.fnc