perlapi: Document sv_dup(_inc)?

Author: khwilliamson

embed.fnc

@@ -6360,9 +6360,9 @@ CRdp	|PERL_SI *|si_dup	|NULLOK PERL_SI *si			\
 				|NN CLONE_PARAMS *param
 CRdp	|ANY *	|ss_dup 	|NN PerlInterpreter *proto_perl 	\
 				|NN CLONE_PARAMS *param
-ARp	|SV *	|sv_dup 	|NULLOK const SV * const ssv		\
+CRdp	|SV *	|sv_dup 	|NULLOK const SV * const ssv		\
 				|NN CLONE_PARAMS * const param
-ARp	|SV *	|sv_dup_inc	|NULLOK const SV * const ssv		\
+CRdp	|SV *	|sv_dup_inc	|NULLOK const SV * const ssv		\
 				|NN CLONE_PARAMS * const param
 # if defined(PERL_IN_OP_C) || defined(PERL_IN_PEEP_C)
 p	|void	|op_relocate_sv |NN SV **svp				\

sv.c

@@ -15054,6 +15054,35 @@ S_sv_dup_common(pTHX_ const SV *const ssv, CLONE_PARAMS *const param)
     return dsv;
  }
 
+/*
+=for apidoc      sv_dup
+=for apidoc_item sv_dup_inc
+
+In spite of their generic names, these are very specialized functions mainly
+for use when cloning an interpreter instance.  You are probably looking for
+L<perlapi/newSVsv>.
+
+They duplicate an SV of any type (not just a plain SV, but including AV, HV
+I<etc>.), returning a pointer to the cloned object.  The difference is that the
+new SV under C<sv_dup> has a reference count of 0, but 1 under C<sv_dup_inc>.
+Only specialized cases will want a zero reference count, almost certainly only
+when you aren't already holding a reference.  Thus, you almost always want to
+use the C<sv_dup_inc> form.
+
+The cloning process uses use a cache, so that if a particular SV address has
+already been duped, that duped SV is returned again rather than creating a
+second duplicate.
+
+C<param> has type S<C<CLONE_PARAMS *>>.  This is mostly for internal core use
+when duplicating something more complicated than an SV (code in common is
+used).  Your code may inherit this parameter, which you merely pass on, but you
+can initialize it by using C<clone_params_new>.  Don't forget to
+free it when done, via C<clone_params_del>>.  Its only member that is
+public is C<flags>, all which are documented in L<perlapi/perl_clone>.
+
+=cut
+ */
+
 SV *
 Perl_sv_dup_inc(pTHX_ const SV *const ssv, CLONE_PARAMS *const param)
 {