perlapi: Document sv_dup(_inc)?

[khwilliamson]

No description provided.

[Leont]

That first paragraph probably needs an additional sentence along the lines of The latter is almost always what you want., but I'm not sure how to explain why. Basically you should used the _inc variant if the source location owned a refcount on the SV.

[iabyn]

The new pod for this is making my skin tingle. sv_dup() is a highly specialised function for cloning an arbitrary SV into a new interpreter - principally used during ithreads thread creation. The new POD for this function makes it sound instead like it's a general-purpose SV-copying function. I'm not sure in principle whether this function should even be in the API.

…

-- Diplomacy is telling someone to go to hell in such a way that they'll look forward to the trip

[Leont]

The new pod for this is making my skin tingle.

sv_dup() is a highly specialised function for cloning an arbitrary SV into a new interpreter - principally used during ithreads thread creation.

The new POD for this function makes it sound instead like it's a general-purpose SV-copying function.

I think a lot of the recently added documentation is focused on what a function does, not why you'd want to use it. It's the common order of documenting things, but in this case that works out less than ideally.

I'm not sure in principle whether this function should even be in the API.

It should IMO. They are used on CPAN to clone data, and there's literally no other way to do such a thing. The main issue IME is that the CLONE_PARAMS isn't available everyhere where one may want to use this

[khwilliamson]

This patch was reverted due to the contention at the deadline. improvement suggestions welcome!