perlapi: Document sv_dup(_inc)?

2 files changed, 23 insertions, 2 deletions

diff --git a/embed.fnc b/embed.fnc
index a5f609356a..6870287eee 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -2829,8 +2829,8 @@ S	|SV **	|sv_dup_inc_multiple|NN SV *const *source|NN SV **dest \
 SR	|SV*	|sv_dup_common	|NN const SV *const ssv \
 				|NN CLONE_PARAMS *const param
 #endif
-ApR	|SV*	|sv_dup		|NULLOK const SV *const ssv|NN CLONE_PARAMS *const param
-ApR	|SV*	|sv_dup_inc	|NULLOK const SV *const ssv \
+ApdR	|SV*	|sv_dup		|NULLOK const SV *const ssv|NN CLONE_PARAMS *const param
+ApdR	|SV*	|sv_dup_inc	|NULLOK const SV *const ssv \
 				|NN CLONE_PARAMS *const param
 Cp	|void	|rvpv_dup	|NN SV *const dsv|NN const SV *const ssv|NN CLONE_PARAMS *const param
 Cp	|yy_parser*|parser_dup	|NULLOK const yy_parser *const proto|NN CLONE_PARAMS *const param
diff --git a/sv.c b/sv.c
index 16bba941cb..11bed2c44d 100644
--- a/sv.c
+++ b/sv.c
@@ -14625,6 +14625,27 @@ 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
+
+These duplicate an SV of any type (including AV, HV 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.
+
+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 L</C<clone_params_new>>.  Don't forget to free it
+when done, via L</C<clone_params_del>>.  Its only member that is public is
+C<flags>, all which are documented in L</C<perl_clone>>.
+
+=cut
+ */
+
 SV *
 Perl_sv_dup_inc(pTHX_ const SV *const ssv, CLONE_PARAMS *const param)
 {