doc: clarify intent of CS C-to-Racket calling API

pkgs/racket-doc/scribblings/inside/cs-eval.scrbl

@@ -7,7 +7,7 @@
 The @cppi{racket_apply} function provides basic evaluation support,
 but @cppi{racket_eval}, @cppi{racket_dynamic_require}, and
 @cppi{racket_namespace_require} provide higher-level support for the
-most common evaluation tasks.
+most common evaluation tasks to initialize a Racket instance.
 
 @function[(ptr racket_eval [ptr s_expr])]{
 
@@ -21,7 +21,11 @@ Use @cppi{racket_namespace_require} to initialize a namespace, or use
 @cppi{racket_dynamic_require} to access functionality without going
 through a top-level namespace. Although those functions are the same
 as using @racket[namespace-require] and @racket[dynamic-require], they
-work without having those identifiers bound in a namespace already.}
+work without having those identifiers bound in a namespace already.
+
+This function and others in this section are not meant to be called
+in C code that was called from Racket. See also @secref["cs-procs"]
+for a discussion of @emph{entry} points versus @emph{re-entry} points.}
 
 @function[(ptr racket_dynamic_require [ptr module_path] [ptr sym_or_false])]{
 

pkgs/racket-doc/scribblings/inside/cs-procs.scrbl

@@ -3,13 +3,21 @@
 
 @title[#:tag "cs-procs"]{Calling Procedures}
 
-Normally, C programs should call Racket procedures by using
+As an entry point into Racket, C programs should normally call Racket
-@cppi{racket_apply}, which calls the procedure in the initial Racket
+procedures by using @cppi{racket_apply}, which calls the procedure in
-thread of the main Racket place. Chez Scheme entry points such as
+the initial Racket thread of the main Racket place. Chez Scheme entry
-@cppi{Scall0} and @cppi{Scall} directly call a procedure outside of
+points such as @cppi{Scall0} and @cppi{Scall} directly call a
-any Racket thread, which will not work correctly with Racket
+procedure outside of any Racket thread, which will not work correctly
-facilities such as threads, parameters, continuations, or continuation
+with Racket facilities such as threads, parameters, continuations, or
-marks.
+continuation marks.
+
+The functions in this section are meant to be used as an entry point
+to Racket, but not as a @emph{re-entry} point. When Racket calls a C
+function that in turn calls back into Racket, the best approach is to
+use the FFI (see @other-doc['(lib
+"scribblings/foreign/foreign.scrbl")]) so that the C call recieves a
+Racket callback that is wrapped as a plain C callback. That way, the
+FFI can handle the details of boundary crossings between Racket and C.
 
 @; ----------------------------------------------------------------------
 

pkgs/racket-doc/scribblings/inside/cs-start.scrbl

@@ -125,4 +125,8 @@ functions, and @DFlag{c-mods} mode generates C code that calls
 If @var{as_predefined} is true, then the code is loaded during the
 creation of any new Racket @tech[#:doc reference-doc]{place} in the
 new place, so that modules declared by the code are loaded in the new
-place, too.}
+place, too.
+
+These functions are not meant to be called in C code that was called
+from Racket. See also @secref["cs-procs"] for a discussion of
+@emph{entry} points versus @emph{re-entry} points.}