From b5582bb6dc31e988de5c33ebb28932901c2206ae Mon Sep 17 00:00:00 2001
From: ripley <ripley@00db46b3-68df-0310-9c12-caf00c1e9a41>
Date: Sat, 4 May 2024 07:48:58 +0000
Subject: [PATCH] update comments

git-svn-id: https://svn.r-project.org/R/trunk@86521 00db46b3-68df-0310-9c12-caf00c1e9a41
---
 src/include/R_ext/RS.h          | 17 ++++++++++-------
 src/include/R_ext/Rallocators.h |  3 ++-
 src/include/R_ext/Rdynload.h    |  9 ++++++++-
 src/include/R_ext/Utils.h       |  9 +++++----
 4 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/src/include/R_ext/RS.h b/src/include/R_ext/RS.h
index 8ab58dfdbb2..d6c4717ca20 100644
--- a/src/include/R_ext/RS.h
+++ b/src/include/R_ext/RS.h
@@ -21,7 +21,7 @@
  *  https://www.R-project.org/Licenses/
  */
 
-/* Included by R.h: mainly API */
+/* Included by R.h: nowadays almost all API */
 
 #ifndef R_RS_H
 #define R_RS_H
@@ -44,29 +44,32 @@ extern "C" {
 
 /* S Like Memory Management */
 
+/* not of themselves API */
 extern void *R_chk_calloc(R_SIZE_T, R_SIZE_T);
 extern void *R_chk_realloc(void *, R_SIZE_T);
 extern void R_chk_free(void *);
 
 #ifndef STRICT_R_HEADERS
-/* S-PLUS 3.x but not 5.x NULLed the pointer in Free */
+/* S-PLUS 3.x but not 5.x NULLed the pointer in Free.
+   Not API.
+*/
 #define Calloc(n, t)   (t *) R_chk_calloc( (R_SIZE_T) (n), sizeof(t) )
 #define Realloc(p,n,t) (t *) R_chk_realloc( (void *)(p), (R_SIZE_T)((n) * sizeof(t)) )
 #define Free(p)        (R_chk_free( (void *)(p) ), (p) = NULL)
 #endif
-    
+
+/* API */
 #define R_Calloc(n, t)   (t *) R_chk_calloc( (R_SIZE_T) (n), sizeof(t) )
 #define R_Realloc(p,n,t) (t *) R_chk_realloc( (void *)(p), (R_SIZE_T)((n) * sizeof(t)) )
 #define R_Free(p)      (R_chk_free( (void *)(p) ), (p) = NULL)
 
-/* undocumented until 4.1.2: widely used. */
+/* Nowadays API: undocumented until 4.1.2: widely used. */
 #define Memcpy(p,q,n)  memcpy( p, q, (R_SIZE_T)(n) * sizeof(*p) )
 
-/* added for 3.0.0 but undocumented until 4.1.2.
-   Used by a couple of packages. */
+/* Nowadays API: added for 3.0.0 but undocumented until 4.1.2. */
 #define Memzero(p,n)  memset(p, 0, (R_SIZE_T)(n) * sizeof(*p))
 
-/* Added in R 2.6.0 */
+/* API: Added in R 2.6.0 */
 #define CallocCharBuf(n) (char *) R_chk_calloc(((R_SIZE_T)(n))+1, sizeof(char))
 
 /* S Like Fortran Interface */
diff --git a/src/include/R_ext/Rallocators.h b/src/include/R_ext/Rallocators.h
index 6878300d806..cdb89a50d52 100644
--- a/src/include/R_ext/Rallocators.h
+++ b/src/include/R_ext/Rallocators.h
@@ -24,7 +24,8 @@
  *  Definition of the R_allocator_t structure for custom allocators
  *  to be used with allocVector3()
  *
- * Not API
+ *  allocVector3 is also not declared as API in
+ * Rinternals.h nor documented in R-ests.
  */
 
 #ifndef R_EXT_RALLOCATORS_H_
diff --git a/src/include/R_ext/Rdynload.h b/src/include/R_ext/Rdynload.h
index 056f8b5f217..a24f609c1ba 100644
--- a/src/include/R_ext/Rdynload.h
+++ b/src/include/R_ext/Rdynload.h
@@ -85,16 +85,21 @@ int R_registerRoutines(DllInfo *info, const R_CMethodDef * const croutines,
 Rboolean R_useDynamicSymbols(DllInfo *info, Rboolean value);
 Rboolean R_forceSymbols(DllInfo *info, Rboolean value);
 
+/* Not API */
 DllInfo *R_getDllInfo(const char *name);
 
 /* To be used by applications embedding R to register their symbols
-   that are not related to any dynamic module */
+   that are not related to any dynamic module/
+
+   Not API
+*/
 DllInfo *R_getEmbeddingDllInfo(void);
 
 typedef struct Rf_RegisteredNativeSymbol R_RegisteredNativeSymbol;
 typedef enum {R_ANY_SYM=0, R_C_SYM, R_CALL_SYM, R_FORTRAN_SYM, R_EXTERNAL_SYM} NativeSymbolType;
 
 
+/* Not API */
 DL_FUNC R_FindSymbol(char const *, char const *,
 		       R_RegisteredNativeSymbol *symbol);
 
@@ -103,6 +108,8 @@ DL_FUNC R_FindSymbol(char const *, char const *,
    for use from C code in a package.  The registration part probably
    ought to be integrated with the other registrations.  The naming of
    these routines may be less than ideal.
+
+   Declarations in the manual, so API
 */
 
 void R_RegisterCCallable(const char *package, const char *name, DL_FUNC fptr);
diff --git a/src/include/R_ext/Utils.h b/src/include/R_ext/Utils.h
index 69d40adce7a..47a473cafcb 100644
--- a/src/include/R_ext/Utils.h
+++ b/src/include/R_ext/Utils.h
@@ -83,12 +83,11 @@ const char *R_ExpandFileName(const char *);
 // not API
 const char *R_ExpandFileNameUTF8(const char *);
 #endif
-// this group is not API
-/*
-  attribute_hidden and no longer used.
+/*  attribute_hidden and no longer used.
 void	setIVector(int*, int, int);
 void	setRVector(double*, int, double);
 */
+/* Not API */
 Rboolean StringFalse(const char *); // used by iotools
 Rboolean StringTrue(const char *); // used by iotools
 Rboolean isBlankString(const char *); // used by iotools and openxlsx2
@@ -108,7 +107,9 @@ void R_CheckStack(void);
 void R_CheckStack2(R_SIZE_T);
 
 
-/* ../../appl/interv.c: first also in Applic.h */
+/* ../../appl/interv.c: first also in Applic.h 
+   Both are API
+*/
 int findInterval(double *xt, int n, double x,
 		 Rboolean rightmost_closed,  Rboolean all_inside, int ilo,
 		 int *mflag);