start annotating the use of Rboolean in public headers

git-svn-id: https://svn.r-project.org/R/trunk@87938 00db46b3-68df-0310-9c12-caf00c1e9a41

Author: ripley

src/include/Rinternals.h

@@ -203,7 +203,7 @@ typedef struct SEXPREC *SEXP;
 #define CHAR(x) R_CHAR(x)
 const char *(R_CHAR)(SEXP x);
 
-/* Various tests with macro versions in the internal headers */
+/* Various tests with macro versions in the internal headers such as Defn.h */
 Rboolean (Rf_isNull)(SEXP s);
 Rboolean (Rf_isSymbol)(SEXP s);
 Rboolean (Rf_isLogical)(SEXP s);
@@ -510,12 +510,12 @@ SEXP Rf_allocS4Object(void);
 SEXP Rf_allocSExp(SEXPTYPE);
 // next is not documented but generated by inlined calls to Rf_allocVector
 SEXP Rf_allocVector3(SEXPTYPE, R_xlen_t, R_allocator_t*);
-R_xlen_t Rf_any_duplicated(SEXP x, Rboolean from_last);
-R_xlen_t Rf_any_duplicated3(SEXP x, SEXP incomp, Rboolean from_last);
+R_xlen_t Rf_any_duplicated(SEXP x, Rboolean from_last); // unique.c
+R_xlen_t Rf_any_duplicated3(SEXP x, SEXP incomp, Rboolean from_last); // unique.c
 SEXP Rf_classgets(SEXP, SEXP);
 SEXP Rf_cons(SEXP, SEXP);
-void Rf_copyMatrix(SEXP, SEXP, Rboolean);
-void Rf_copyListMatrix(SEXP, SEXP, Rboolean);
+void Rf_copyMatrix(SEXP, SEXP, Rboolean); // duplicate.c
+void Rf_copyListMatrix(SEXP, SEXP, Rboolean); // duplicate.c
 void Rf_copyMostAttrib(SEXP, SEXP);
 void Rf_copyVector(SEXP, SEXP);
 void Rf_defineVar(SEXP, SEXP, SEXP);
@@ -527,15 +527,15 @@ SEXP R_duplicate_attr(SEXP);
 SEXP R_shallow_duplicate_attr(SEXP);
 SEXP Rf_lazy_duplicate(SEXP);
 /* the next really should not be here and is also in Defn.h */
-SEXP Rf_duplicated(SEXP, Rboolean);
+SEXP Rf_duplicated(SEXP, Rboolean); // duplicate.c
 SEXP Rf_eval(SEXP, SEXP);
 SEXP Rf_findFun(SEXP, SEXP);
 SEXP Rf_findVar(SEXP, SEXP);
 SEXP Rf_findVarInFrame(SEXP, SEXP);
-SEXP Rf_findVarInFrame3(SEXP, SEXP, Rboolean);
+SEXP Rf_findVarInFrame3(SEXP, SEXP, Rboolean); // envir.c
 Rboolean R_existsVarInFrame(SEXP, SEXP);
-SEXP R_getVar(SEXP, SEXP, Rboolean);
-SEXP R_getVarEx(SEXP, SEXP, Rboolean, SEXP);
+SEXP R_getVar(SEXP, SEXP, Rboolean); // envir.c
+SEXP R_getVarEx(SEXP, SEXP, Rboolean, SEXP); // envir.c
 void R_removeVarFromFrame(SEXP, SEXP);
 SEXP Rf_getAttrib(SEXP, SEXP);
 SEXP Rf_GetArrayDimnames(SEXP);
@@ -551,19 +551,19 @@ SEXP Rf_install(const char *);
 SEXP Rf_installChar(SEXP);
 SEXP Rf_installNoTrChar(SEXP);
 SEXP Rf_installTrChar(SEXP);
-Rboolean Rf_isOrdered(SEXP);
-Rboolean Rf_isUnordered(SEXP);
-Rboolean Rf_isUnsorted(SEXP, Rboolean);
-Rboolean R_isTRUE(SEXP);
+Rboolean Rf_isOrdered(SEXP); // util.c
+Rboolean Rf_isUnordered(SEXP); // util.c
+Rboolean Rf_isUnsorted(SEXP, Rboolean); // sort.c
+Rboolean R_isTRUE(SEXP); // util.c
 SEXP Rf_lengthgets(SEXP, R_len_t);
 SEXP Rf_xlengthgets(SEXP, R_xlen_t);
-SEXP R_lsInternal(SEXP, Rboolean);
-SEXP R_lsInternal3(SEXP, Rboolean, Rboolean);
+SEXP R_lsInternal(SEXP, Rboolean); // envir.c
+SEXP R_lsInternal3(SEXP, Rboolean, Rboolean); // envir.c
 SEXP Rf_match(SEXP, SEXP, int);
 SEXP Rf_namesgets(SEXP, SEXP);
 SEXP Rf_mkChar(const char *);
 SEXP Rf_mkCharLen(const char *, int);
-Rboolean Rf_NonNullStringMatch(SEXP, SEXP);
+Rboolean Rf_NonNullStringMatch(SEXP, SEXP); // match.c
 int Rf_ncols(SEXP);
 int Rf_nrows(SEXP);
 SEXP Rf_nthcdr(SEXP, int);
@@ -582,7 +582,7 @@ SEXP Rf_protect(SEXP);
 SEXP Rf_setAttrib(SEXP, SEXP, SEXP);
 void Rf_setVar(SEXP, SEXP, SEXP);
 SEXPTYPE Rf_str2type(const char *);
-Rboolean Rf_StringBlank(SEXP);
+Rboolean Rf_StringBlank(SEXP); // util.c
 SEXP Rf_substitute(SEXP,SEXP);
 SEXP Rf_topenv(SEXP, SEXP);
 const char * Rf_translateChar(SEXP);
@@ -608,8 +608,8 @@ SEXP R_tryEval(SEXP, SEXP, int *);
 SEXP R_tryEvalSilent(SEXP, SEXP, int *);
 SEXP R_GetCurrentEnv(void);
 
-Rboolean Rf_isS4(SEXP);
-SEXP Rf_asS4(SEXP, Rboolean, int);
+Rboolean Rf_isS4(SEXP); // objects.c
+SEXP Rf_asS4(SEXP, Rboolean, int); // objects.c
 SEXP Rf_S3Class(SEXP);
 int Rf_isBasicClass(const char *);
 
@@ -625,9 +625,9 @@ typedef enum {
 } cetype_t;
 
 cetype_t Rf_getCharCE(SEXP);
-Rboolean Rf_charIsASCII(SEXP);
-Rboolean Rf_charIsUTF8(SEXP);
-Rboolean Rf_charIsLatin1(SEXP);
+Rboolean Rf_charIsASCII(SEXP); // sysutils.c
+Rboolean Rf_charIsUTF8(SEXP);  // sysutils.c
+Rboolean Rf_charIsLatin1(SEXP); // sysutils.c
 SEXP Rf_mkCharCE(const char *, cetype_t);
 SEXP Rf_mkCharLenCE(const char *, int, cetype_t);
 const char *Rf_reEnc(const char *x, cetype_t ce_in, cetype_t ce_out, int subst);
@@ -655,15 +655,15 @@ DL_FUNC R_ExternalPtrAddrFn(SEXP s);
 
 /* Finalization interface */
 typedef void (*R_CFinalizer_t)(SEXP);
-void R_RegisterFinalizer(SEXP s, SEXP fun);
-void R_RegisterCFinalizer(SEXP s, R_CFinalizer_t fun);
-void R_RegisterFinalizerEx(SEXP s, SEXP fun, Rboolean onexit);
-void R_RegisterCFinalizerEx(SEXP s, R_CFinalizer_t fun, Rboolean onexit);
+void R_RegisterFinalizer(SEXP s, SEXP fun); 
+void R_RegisterCFinalizer(SEXP s, R_CFinalizer_t fun); // memory,c
+void R_RegisterFinalizerEx(SEXP s, SEXP fun, Rboolean onexit); // memory,c
+void R_RegisterCFinalizerEx(SEXP s, R_CFinalizer_t fun, Rboolean onexit);  // memory,c
 void R_RunPendingFinalizers(void);
 
 /* Weak reference interface */
-SEXP R_MakeWeakRef(SEXP key, SEXP val, SEXP fin, Rboolean onexit);
-SEXP R_MakeWeakRefC(SEXP key, SEXP val, R_CFinalizer_t fin, Rboolean onexit);
+SEXP R_MakeWeakRef(SEXP key, SEXP val, SEXP fin, Rboolean onexit);  // memory,c
+SEXP R_MakeWeakRefC(SEXP key, SEXP val, R_CFinalizer_t fin, Rboolean onexit);  // memory,c
 SEXP R_WeakRefKey(SEXP w);
 SEXP R_WeakRefValue(SEXP w);
 void R_RunWeakRefFinalizer(SEXP w);
@@ -673,7 +673,7 @@ SEXP R_ClosureExpr(SEXP);
 SEXP R_BytecodeExpr(SEXP e);
 
 /* Protected evaluation */
-Rboolean R_ToplevelExec(void (*fun)(void *), void *data);
+Rboolean R_ToplevelExec(void (*fun)(void *), void *data); // context.c
 SEXP R_ExecWithCleanup(SEXP (*fun)(void *), void *data,
 		       void (*cleanfun)(void *), void *cleandata);
 SEXP R_tryCatch(SEXP (*)(void *), void *,       /* body closure*/
@@ -688,25 +688,25 @@ SEXP R_MakeUnwindCont(void);
 NORET void R_ContinueUnwind(SEXP cont);
 SEXP R_UnwindProtect(SEXP (*fun)(void *data), void *data,
                      void (*cleanfun)(void *data, Rboolean jump),
-                     void *cleandata, SEXP cont);
+                     void *cleandata, SEXP cont); // context.c
 
 /* Environment and Binding Features */
 SEXP R_NewEnv(SEXP, int, int);
-Rboolean R_IsPackageEnv(SEXP rho);
+Rboolean R_IsPackageEnv(SEXP rho); // envir.c
 SEXP R_PackageEnvName(SEXP rho);
 SEXP R_FindPackageEnv(SEXP info);
-Rboolean R_IsNamespaceEnv(SEXP rho);
+Rboolean R_IsNamespaceEnv(SEXP rho); // envir.c
 SEXP R_NamespaceEnvSpec(SEXP rho);
 SEXP R_FindNamespace(SEXP info);
 void R_LockEnvironment(SEXP env, Rboolean bindings);
-Rboolean R_EnvironmentIsLocked(SEXP env);
+Rboolean R_EnvironmentIsLocked(SEXP env); // envir.c
 void R_LockBinding(SEXP sym, SEXP env);
 void R_unLockBinding(SEXP sym, SEXP env);
 void R_MakeActiveBinding(SEXP sym, SEXP fun, SEXP env);
-Rboolean R_BindingIsLocked(SEXP sym, SEXP env);
-Rboolean R_BindingIsActive(SEXP sym, SEXP env);
+Rboolean R_BindingIsLocked(SEXP sym, SEXP env); // envir.c
+Rboolean R_BindingIsActive(SEXP sym, SEXP env); // envir.c
 SEXP R_ActiveBindingFunction(SEXP sym, SEXP env);
-Rboolean R_HasFancyBindings(SEXP rho);
+Rboolean R_HasFancyBindings(SEXP rho); // envir.c
 
 
 /* ../main/errors.c : */
@@ -865,12 +865,15 @@ int R_system(const char *);
 #define IDENT_USE_CLOENV      16
 #define IDENT_USE_SRCREF      32
 #define IDENT_EXTPTR_AS_REF   64
-Rboolean R_compute_identical(SEXP, SEXP, int);
+Rboolean R_compute_identical(SEXP, SEXP, int); // identical.c
 
 SEXP R_body_no_src(SEXP x); // body(x) without "srcref" etc, ../main/utils.c
 
 /* C version of R's  indx <- order(..., na.last, decreasing) :
-   e.g.  arglist = Rf_lang2(x,y)  or  Rf_lang3(x,y,z) */
+   e.g.  arglist = Rf_lang2(x,y)  or  Rf_lang3(x,y,z) 
+
+   In sort.c
+*/
 void R_orderVector (int *indx, int n, SEXP arglist, Rboolean nalast, Rboolean decreasing);
 // C version of R's  indx <- order(x, na.last, decreasing) :
 void R_orderVector1(int *indx, int n, SEXP x,       Rboolean nalast, Rboolean decreasing);
@@ -1247,7 +1250,7 @@ void (SET_S4_OBJECT)(SEXP x); // used by Rcpp (not?) RTMB RcppInt64 data.table f
 void (UNSET_S4_OBJECT)(SEXP x); // used by Rcpp (not?) collapse data.table essentials slam vctrs
 const char *R_curErrorBuf(void); // used by Rserve gert unix
 int (IS_SCALAR)(SEXP x, int type); // used by rbedrock symengine this.path
-Rboolean Rf_psmatch(const char *, const char *, Rboolean); // used by rgl
+Rboolean Rf_psmatch(const char *, const char *, Rboolean); // match.c,  used by rgl
 
 /* used in a couple of packages but should probably be dropped 
    error_return: grr nanonext rJava rbedrock

src/main/character.c

@@ -157,6 +157,7 @@ attribute_hidden SEXP do_nzchar(SEXP call, SEXP op, SEXP args, SEXP env)
        -2 ... the quantity is not computable (bytes encoding)
      semi-internal buffer cbuff is never freed, should be freed by caller
 */
+// in Rinternals.h
 int R_nchar(SEXP string, nchar_type type_,
 	    Rboolean allowNA, Rboolean keepNA, const char* msg_name)
 {

src/main/duplicate.c

@@ -130,6 +130,7 @@ attribute_hidden void reset_duplicate_counter(void)
 }
 #endif
 
+// In Rinternals.h
 SEXP duplicate(SEXP s){
     SEXP t;
 
@@ -405,6 +406,7 @@ void copyVector(SEXP s, SEXP t)
     }
 }
 
+// In Rinternals.h
 void copyListMatrix(SEXP s, SEXP t, Rboolean byrow)
 {
     int nr = nrows(s), nc = ncols(s);
@@ -440,6 +442,7 @@ static R_INLINE SEXP VECTOR_ELT_LD(SEXP x, R_xlen_t i)
     return lazy_duplicate(VECTOR_ELT(x, i));
 }
 
+// In Rinternals.h
 void copyMatrix(SEXP s, SEXP t, Rboolean byrow)
 {
     int nr = nrows(s), nc = ncols(s);

src/main/envir.c

@@ -991,6 +991,7 @@ void R_SetVarLocValue(R_varloc_t vl, SEXP value)
   symbol in this frame (FALSE).  This is used for get() and exists().
 */
 
+// In Rinternals.h
 SEXP findVarInFrame3(SEXP rho, SEXP symbol, Rboolean doGet)
 {
     int hashcode;
@@ -2280,6 +2281,7 @@ attribute_hidden SEXP do_mget(SEXP call, SEXP op, SEXP args, SEXP rho)
     return(ans);
 }
 
+// In Rinternals.h
 SEXP R_getVarEx(SEXP sym, SEXP rho, Rboolean inherits, SEXP ifnotfound)
 {
     if (TYPEOF(sym) != SYMSXP)
@@ -2300,6 +2302,7 @@ SEXP R_getVarEx(SEXP sym, SEXP rho, Rboolean inherits, SEXP ifnotfound)
     return val;
 }
 
+// In Rinternals.h
 SEXP R_getVar(SEXP sym, SEXP rho, Rboolean inherits)
 {
     SEXP val = R_getVarEx(sym, rho, inherits, R_UnboundValue);
@@ -2940,6 +2943,7 @@ attribute_hidden SEXP do_ls(SEXP call, SEXP op, SEXP args, SEXP rho)
 
 /* takes an environment, a boolean indicating whether to get all
    names and a boolean if sorted is desired */
+// In Rinternals.h
 SEXP R_lsInternal3(SEXP env, Rboolean all, Rboolean sorted)
 {
     if(IS_USER_DATABASE(env)) {
@@ -2980,6 +2984,7 @@ SEXP R_lsInternal3(SEXP env, Rboolean all, Rboolean sorted)
 }
 
 /* non-API version used in several packages */
+// in Rinternals.h
 SEXP R_lsInternal(SEXP env, Rboolean all)
 {
     return R_lsInternal3(env, all, TRUE);

src/main/match.c

@@ -46,6 +46,7 @@
 
 
 /* used in subscript.c and subassign.c */
+// In Rinternals.h
 Rboolean NonNullStringMatch(SEXP s, SEXP t)
 {
     /* "" or NA string matches nothing */

src/main/objects.c

@@ -1835,12 +1835,13 @@ SEXP R_get_primname(SEXP object)
 }
 #endif
 
-
+// in Rinternals.h
 Rboolean isS4(SEXP s)
 {
     return IS_S4_OBJECT(s);
 }
 
+// in Rinternals.h
 SEXP asS4(SEXP s, Rboolean flag, int complete)
 {
     if(flag == IS_S4_OBJECT(s))

src/main/sort.c

@@ -1120,7 +1120,7 @@ GREATER_2_SUB_DEF(intdbl2greater,    int, double, icmp, rcmp)
  * to the API */
 
 // Usage:  R_orderVector(indx, n,  Rf_lang2(x,y),  nalast, decreasing)
-// API
+// In Rinternals.h
 void R_orderVector(int *indx, // must be pre-allocated to length >= n
 		   int n,
 		   SEXP arglist, // <- e.g.  Rf_lang2(x,y)
@@ -1133,7 +1133,7 @@ void R_orderVector(int *indx, // must be pre-allocated to length >= n
 }
 
 // Fast version of 1-argument case of R_orderVector()
-// API
+// In Rinternals.h
 void R_orderVector1(int *indx, int n, SEXP x,
 		    Rboolean nalast, Rboolean decreasing)
 {

src/main/sysutils.c

@@ -951,12 +951,14 @@ cetype_t getCharCE(SEXP x)
     else return CE_NATIVE;
 }
 
+// In Rinternals.h
 Rboolean charIsASCII(SEXP x)
 {
     CHECK_CHARSXP(x);
     return IS_ASCII(x) ? TRUE : FALSE;
 }
 
+// In Rinternals.h
 Rboolean charIsUTF8(SEXP x)
 {
     CHECK_CHARSXP(x);
@@ -966,6 +968,7 @@ Rboolean charIsUTF8(SEXP x)
     return TRUE;
 }
 
+// In Rinternals.h
 Rboolean charIsLatin1(SEXP x)
 {
     CHECK_CHARSXP(x);

src/main/unique.c

@@ -861,6 +861,7 @@ static SEXP Duplicated(SEXP x, Rboolean from_last, int nmax)
     return ans;
 }
 
+//In Rinternals.h
 attribute_hidden R_xlen_t sorted_any_duplicated(SEXP x, Rboolean from_last) {
     int itmp, sorted;
     double rtmp;
@@ -977,6 +978,7 @@ attribute_hidden R_xlen_t sorted_any_duplicated(SEXP x, Rboolean from_last) {
 #undef SORTED_ANYDUP_NANS
 
 /* simpler version of the above : return 1-based index of first, or 0 : */
+// In Rinternals.h
 R_xlen_t any_duplicated(SEXP x, Rboolean from_last)
 {
     R_xlen_t result = 0;

src/main/util.c

@@ -181,20 +181,23 @@ SEXP asChar(SEXP x)
     return NA_STRING;
 }
 
+// In Rinternals.h
 Rboolean isUnordered(SEXP s)
 {
     return (TYPEOF(s) == INTSXP
 	    && inherits(s, "factor")
 	    && !inherits(s, "ordered"));
 }
 
+// In Rinternals.h
 Rboolean isOrdered(SEXP s)
 {
     return (TYPEOF(s) == INTSXP
 	    && inherits(s, "factor")
 	    && inherits(s, "ordered"));
 }
 
+// In Rinternals.h
 Rboolean R_isTRUE(SEXP x)
 {
     if (TYPEOF(x) == LGLSXP && XLENGTH(x) == 1) {
@@ -448,7 +451,7 @@ size_t mbcsToUcs2(const char *in, R_ucs2_t *out, int nout, int enc)
 
 #include <wctype.h>
 
-// non-API put used in the internet module and in packages
+// non-API but used in the internet module and in packages
 Rboolean isBlankString(const char *s)
 {
     if(mbcslocale) {
@@ -465,6 +468,7 @@ Rboolean isBlankString(const char *s)
     return TRUE;
 }
 
+// in Rinternals.h
 Rboolean StringBlank(SEXP x)
 {
     if (x == R_NilValue) return TRUE;