Tidy up later_api.h

Author: shikokuchuo

inst/include/later_api.h

@@ -1,6 +1,9 @@
 #ifndef _later_later_api_h
 #define _later_later_api_h
 
+// ---- Platform prerequisites ------------------------------------------------
+// System and R headers required by the later API.
+
 #ifndef R_NO_REMAP
 #define R_NO_REMAP
 #endif
@@ -28,10 +31,8 @@
 
 #include <Rinternals.h>
 
-// Needed for R_GetCCallable on R 3.3 and older; in more recent versions, this
-// is included via Rinternals.h.
-#include <R_ext/Rdynload.h>
-
+// ---- Public API ------------------------------------------------------------
+// The later C++ interface. See the "Using later from C++" vignette for usage.
 
 namespace later {
 
@@ -58,6 +59,10 @@ static int apiVersionRuntime() {
 }
 // # nocov end
 
+// ---- later() ---------------------------------------------------------------
+// Schedule a C function to execute on the main R thread after a delay.
+// Safe to call from any thread.
+
 inline void later(void (*func)(void*), void* data, double secs, int loop_id) {
   // This function works by retrieving the later::execLaterNative2 function
   // pointer using R_GetCCallable the first time it's called (per compilation
@@ -99,6 +104,10 @@ inline void later(void (*func)(void*), void* data, double secs) {
   later(func, data, secs, GLOBAL_LOOP);
 }
 
+// ---- later_fd() ------------------------------------------------------------
+// Schedule a C function with file descriptor polling. Safe to call from any
+// thread. Requires later >= 1.4.1 (API version 3).
+
 // # nocov start
 // tested by cpp-version-mismatch job on CI
 static void later_fd_version_error(void (*func)(int *, void *), void *data, int num_fds, struct pollfd *fds, double secs, int loop_id) {
@@ -144,6 +153,10 @@ inline void later_fd(void (*func)(int *, void *), void *data, int num_fds, struc
 }
 
 
+// ---- BackgroundTask --------------------------------------------------------
+// Helper class for running work on a background thread and returning results
+// on the main R thread. Subclass and implement execute() and complete().
+
 class BackgroundTask {
 
 public:
@@ -210,6 +223,10 @@ class BackgroundTask {
 
 } // namespace later
 
+// ---- Static initialization -------------------------------------------------
+// Ensures later() and later_fd() are initialized on the main R thread before
+// any user code can call them from a background thread.
+
 namespace {
 
 class LaterInitializer {