Perl
perlapi: Combine sv_unref, _flags
When I build this branch, call perldoc pod/perlapi.pod and search for sv_unref_flags, I come to:
"sv_unref"
"sv_unref_flags"
These each unset the RV status of the SV, and decrement the
reference count of whatever was being referenced by the RV. This can
almost be thought of as a reversal of "newSVrv".
The "flags" argument in "sv_unref_flags" can contain
"SV_IMMEDIATE_UNREF" to force the reference count to be decremented
(otherwise the decrementing is conditional on the reference count
being different from one or the reference being a readonly SV).
"sv_unref" merely calls "sv_unref_flags" with "flags" set to zero.
See "SvROK_off".
void sv_unref (SV *sv)
void sv_unref_flags(SV * const ref, const U32 flags)
Other things being equal, I would have expected the display of the two function calls -- the last two lines above -- to appear before the paragraph which begins, The "flags" argument in "sv_unref_flags" can contain.... That way, the reader has already been prompted to note the difference between the two function calls and is mentally set up to be provided with an explanation of that difference.
Is this possible with the program we use to generate pod/perlapi.pod? Would that be a better approach?
That's an interesting idea. I could see adding an apidoc-like command that says insert the prototypes "here" instead of the normal place, at the end of the entry. But the normal place would have to remain the end of the entry, or perhaps replace the list at the top with the full signatures. I will try experimenting with that and if I can get it to look ok to me, will post a PR to that effect.
Even if we did do that, I'm thinking this would be better to say what is in the new version I just pushed