perlapi: Document and make intern hv.c fcns

These similar functions all have macro front ends which should be used
instead.

2 files changed, 53 insertions, 6 deletions

diff --git a/embed.fnc b/embed.fnc
index 08749c8003..250a4ef0f2 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -3522,10 +3522,10 @@ Apod	|void	|hv_assert	|NN HV *hv
 ApdR	|SV*	|hv_scalar	|NN HV *hv
 p	|void	|hv_pushkv	|NN HV *hv|U32 flags
 ApdRx	|SV*	|hv_bucket_ratio|NN HV *hv
-ApoR	|I32*	|hv_riter_p	|NN HV *hv
-ApoR	|HE**	|hv_eiter_p	|NN HV *hv
-Apo	|void	|hv_riter_set	|NN HV *hv|I32 riter
-Apo	|void	|hv_eiter_set	|NN HV *hv|NULLOK HE *eiter
+CpdoR	|I32*	|hv_riter_p	|NN HV *hv
+CpdoR	|HE**	|hv_eiter_p	|NN HV *hv
+Cpdo	|void	|hv_riter_set	|NN HV *hv|I32 riter
+Cpdo	|void	|hv_eiter_set	|NN HV *hv|NULLOK HE *eiter
 Ap	|void   |hv_rand_set    |NN HV *hv|U32 new_xhv_rand
 Ap	|void	|hv_name_set	|NN HV *hv|NULLOK const char *name|U32 len|U32 flags
 pd	|void	|hv_ename_add	|NN HV *hv|NN const char *name|U32 len \
@@ -3539,8 +3539,8 @@ pox	|void	|hv_kill_backrefs	|NN HV *hv
 #endif
 Apd	|void	|hv_clear_placeholders	|NN HV *hv
 XpoR	|SSize_t*|hv_placeholders_p	|NN HV *hv
-ApoR	|I32	|hv_placeholders_get	|NN const HV *hv
-Apo	|void	|hv_placeholders_set	|NN HV *hv|I32 ph
+CpdoR	|I32	|hv_placeholders_get	|NN const HV *hv
+Cpdo	|void	|hv_placeholders_set	|NN HV *hv|I32 ph
 
 : This is indirectly referenced by globals.c. This is somewhat annoying.
 p	|SV*	|magic_scalarpack|NN HV *hv|NN MAGIC *mg
diff --git a/hv.c b/hv.c
index 54fbd8abd7..aa3afd0f62 100644
--- a/hv.c
+++ b/hv.c
@@ -2443,6 +2443,14 @@ Perl_hv_iterinit(pTHX_ HV *hv)
     return HvTOTALKEYS(hv);
 }
 
+/*
+=for apidoc hv_riter_p
+
+Implements C<HvRITER> which you should use instead.
+
+=cut
+*/
+
 I32 *
 Perl_hv_riter_p(pTHX_ HV *hv) {
     struct xpvhv_aux *iter;
@@ -2453,6 +2461,14 @@ Perl_hv_riter_p(pTHX_ HV *hv) {
     return &(iter->xhv_riter);
 }
 
+/*
+=for apidoc hv_eiter_p
+
+Implements C<HvEITER> which you should use instead.
+
+=cut
+*/
+
 HE **
 Perl_hv_eiter_p(pTHX_ HV *hv) {
     struct xpvhv_aux *iter;
@@ -2463,6 +2479,14 @@ Perl_hv_eiter_p(pTHX_ HV *hv) {
     return &(iter->xhv_eiter);
 }
 
+/*
+=for apidoc hv_riter_set
+
+Implements C<HvRITER_set> which you should use instead.
+
+=cut
+*/
+
 void
 Perl_hv_riter_set(pTHX_ HV *hv, I32 riter) {
     struct xpvhv_aux *iter;
@@ -2498,6 +2522,14 @@ Perl_hv_rand_set(pTHX_ HV *hv, U32 new_xhv_rand) {
 #endif
 }
 
+/*
+=for apidoc hv_eiter_set
+
+Implements C<HvEITER_set> which you should use instead.
+
+=cut
+*/
+
 void
 Perl_hv_eiter_set(pTHX_ HV *hv, HE *eiter) {
     struct xpvhv_aux *iter;
@@ -3347,6 +3379,13 @@ Perl_hv_placeholders_p(pTHX_ HV *hv)
     return &(mg->mg_len);
 }
 
+/*
+=for apidoc hv_placeholders_get
+
+Implements C<HvPLACEHOLDERS_get>, which you should use instead.
+
+=cut
+*/
 
 I32
 Perl_hv_placeholders_get(pTHX_ const HV *hv)
@@ -3359,6 +3398,14 @@ Perl_hv_placeholders_get(pTHX_ const HV *hv)
     return mg ? mg->mg_len : 0;
 }
 
+/*
+=for apidoc hv_placeholders_set
+
+Implements C<HvPLACEHOLDERS_set>, which you should use instead.
+
+=cut
+*/
+
 void
 Perl_hv_placeholders_set(pTHX_ HV *hv, I32 ph)
 {