[mc] Add some comments

diff --git a/src/mc/mc_address_space.h b/src/mc/mc_address_space.h
index a154676..49fb7d7 100644 (file)
--- a/src/mc/mc_address_space.h
+++ b/src/mc/mc_address_space.h
@@ -43,6 +43,17 @@ typedef enum e_adress_space_read_flags {
 typedef struct s_mc_address_space s_mc_address_space_t, *mc_address_space_t;
 typedef struct s_mc_address_space_class s_mc_address_space_class_t, *mc_address_space_class_t;
 
+/** Abstract base class for an address space
+ *
+ *  This is the base class for all virtual address spaces (process, snapshot).
+ *  It uses dynamic dispatch based on a vtable (`address_space_class`).
+ */
+struct s_mc_address_space {
+  mc_address_space_class_t address_space_class;
+};
+
+/** Class object (vtable) for the virtual address spaces
+ */
 struct s_mc_address_space_class {
   const void* (*read)(
     mc_address_space_t address_space, e_adress_space_read_flags_t flags,
@@ -50,15 +61,12 @@ struct s_mc_address_space_class {
     int process_index);
 };
 
-/** Base class for an address space (process and snapshot)
- */
-struct s_mc_address_space {
-  mc_address_space_class_t address_space_class;
-};
-
 // ***** Virtual/non-final methods
 
-/** Read data from the given address space */
+/** Read data from the given address space
+ *
+ *  Dynamic dispatch.
+ */
 static inline __attribute__((always_inline))
 const void* MC_address_space_read(
   mc_address_space_t address_space, e_adress_space_read_flags_t flags,

diff --git a/src/mc/mc_base.c b/src/mc/mc_base.c
index 34a5bad..96c14b2 100644 (file)
--- a/src/mc/mc_base.c
+++ b/src/mc/mc_base.c
@@ -17,9 +17,6 @@
 
 XBT_LOG_NEW_CATEGORY(mc, "All MC categories");
 
-/**
- * \brief Schedules all the process that are ready to run
- */
 void MC_wait_for_requests(void)
 {
   smx_process_t process;

diff --git a/src/mc/mc_base.h b/src/mc/mc_base.h
index 7027a93..00a453a 100644 (file)
--- a/src/mc/mc_base.h
+++ b/src/mc/mc_base.h
@@ -14,12 +14,29 @@
 
 SG_BEGIN_DECL()
 
-// This variable is set by simgrid-mc in order to enable MC support in the
-// children MC processes:
+/** Environment variable name set by `simgrid-mc` to enable MC support in the
+ *  children MC processes
+ */
 #define MC_ENV_VARIABLE "SIMGRIC_MC"
 
+/** Check if the given simcall can be resolved
+ *
+ *  \return `TRUE` or `FALSE`
+ */
 int MC_request_is_enabled(smx_simcall_t req);
+
+/** Check if the given simcall is visible
+ *
+ *  \return `TRUE` or `FALSE`
+ */
 int MC_request_is_visible(smx_simcall_t req);
+
+/** Execute everything which is invisible
+ *
+ *  Execute all the processes that are ready to run and all invisible simcalls
+ *  iteratively until there doesn't remain any. At this point, the function
+ *  returns to the caller which can handle the visible (and ready) simcalls.
+ */
 void MC_wait_for_requests(void);
 
 extern double *mc_time;