perlapi: Mark internal and better document some memory fcns

Perl_(([cm]|re)alloc|mfree) should not be used by the public; instead
there are macros that these implement.

The *alloc functions weren't documented, because of an erroneous
assumption; erroneous because all require the Perl_ preface to call
them.

2 files changed, 31 insertions, 8 deletions

diff --git a/embed.fnc b/embed.fnc
index 7344deb210..fbc92d30a1 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -599,10 +599,10 @@ ATo	|PerlInterpreter*|perl_clone_using \
 #  endif
 #endif
 
-AaTophd	|Malloc_t|malloc	|MEM_SIZE nbytes
-AaTophd	|Malloc_t|calloc	|MEM_SIZE elements|MEM_SIZE size
-ARTophd	|Malloc_t|realloc	|Malloc_t where|MEM_SIZE nbytes
-ATop	|Free_t	|mfree		|Malloc_t where
+CaTopd	|Malloc_t|malloc	|MEM_SIZE nbytes
+CaTopd	|Malloc_t|calloc	|MEM_SIZE elements|MEM_SIZE size
+CRTopd	|Malloc_t|realloc	|Malloc_t where|MEM_SIZE nbytes
+CTopd	|Free_t	|mfree		|Malloc_t where
 #if defined(MYMALLOC)
 TpR	|MEM_SIZE|malloced_size	|NN void *p
 TpR	|MEM_SIZE|malloc_good_size	|size_t nbytes
diff --git a/malloc.c b/malloc.c
index fe90996096..396cf3f368 100644
--- a/malloc.c
+++ b/malloc.c
@@ -1223,11 +1223,10 @@ S_adjust_size_and_find_bucket(size_t *nbytes_p)
 }
 
 /*
-These have the same interfaces as the C lib ones, so are considered documented
-
 =for apidoc malloc
-=for apidoc calloc
-=for apidoc realloc
+
+Implements L<perlapi/C<Newx>> which you should use instead.
+
 =cut
 */
 
@@ -1796,6 +1795,14 @@ morecore(int bucket)
 #endif /* !PACK_MALLOC */
 }
 
+/*
+=for apidoc mfree
+
+Implements L<perlapi/C<Safefree>> which you should use instead.
+
+=cut
+*/
+
 Free_t
 Perl_mfree(Malloc_t where)
 {
@@ -1886,6 +1893,14 @@ Perl_mfree(Malloc_t where)
         MALLOC_UNLOCK;
 }
 
+/*
+=for apidoc realloc
+
+Implements L<perlapi/C<Renew>> which you should use instead.
+
+=cut
+*/
+
 /* There is no need to do any locking in realloc (with an exception of
    trying to grow in place if we are at the end of the chain).
    If somebody calls us from a different thread with the same address,
@@ -2083,6 +2098,14 @@ Perl_realloc(void *mp, size_t nbytes)
         return ((Malloc_t)res);
 }
 
+/*
+=for apidoc calloc
+
+Implements L<perlapi/C<Newxz>> which you should use instead.
+
+=cut
+*/
+
 Malloc_t
 Perl_calloc(size_t elements, size_t size)
 {