src/fsm/* modifies several names:

* - in fsm_trigger_log_init(), fsm_trigger_log_close() the word **trigger** is
 * replaced by **relay**
 * - fsm_log_struct_unit is replaced by: fsm_log_unit_struct
 *
 * docs/rtfm/intro (previously 'Once upon a time'... 🙃️) is also renamed and
 * extended.
 *

include/fsm.h

@@ -1,29 +1,15 @@
 /**
  * @file
- * Client fsm (finite state machine) header
+ * This file is part of Gem-graph; Client fsm (finite state machine) header.
- *
- * This file is part of Gem-graph.
- *
- *
- * This commit introduces:
- *
- * - the two functions that enable main() to init and close the log:
- *   fsm_trigger_log_init() and fsm_trigger_log_close()
- *
- * - the two functions that enable main() to init and close the fsm:
- *   fsm_init() and fsm_close()
- *
- * - the two functions that enable the fsm to init and close its structures:
- *   fsm_structures_init() and fsm_structures_close()
- *
  *
  * @see readme.docs and this text below.
  *
  * ---
  *
- * The two log structures and the two enums listed below stay in the fsm header.
+ * The two log structures and the two enums listed below are defined in the fsm
+ * header.
  *
- * All log functions are now in dedicated files.
+ * All log functions are in dedicated files.
  *
  * The most important function: fsm_add_log() is in the file:
  * /src/fsm/log/manager.c
@@ -121,18 +107,18 @@
  */
 enum fsm_enum_log_severity {
     FATAL,  /**< (or CRITICAL) an unrecoverable failure that prevents the whole
-                 application from doing any further useful work */
+                 application from doing any further useful work 🕳️☠️ */
     ERROR,  /**< an irremediable situation that hinders the execution of a
-                 specific operation within the application */
+                 specific operation within the application 👀️😮️ */
     WARN,   /**< something unexpected has occurred, but the application can
-                 continue to function normally for the time being */
+                 continue to function normally for the time being 😅️ */
     INFO,   /**< (or MESSAGE) a significant event occurs while the system is
-                 operating normally */
+                 operating normally 📜️👌️ */
     DEBUG,  /**< a description of system states in sufficient detail to give
-                 developers clues as to the cause of an error */
+                 developers clues as to the cause of an error 🪳️👀️🧐️ */
     TRACE   /**< provides a systematic overview of code execution but comes at
-                 a cost in terms of performance */
+                 a cost in terms of performance 🥱️ */
-};
+};//.😮️🧐️👀️😅️😕️😱️😦️🕳️😵‍💫️
 
 /**
  * A list of structures or states that may be involved in program events.
@@ -192,22 +178,22 @@ enum fsm_enum_log_source {
  * @callergraph
  * @see fsm_log_struct
  */
-typedef struct  fsm_log_struct_unit
+typedef struct  fsm_log_unit_struct
                 {
                     long yy_dd_mm; /**< * date of the event reported in the log */
                     long usec;     /**< * with microseconds precision */
                     const char *file_source;     /**< * emitter file */
                     const char *function_source; /**< * emitter function */
                     const char *string_value;    /**< * any event descriptors */
-                    struct fsm_log_struct_unit *prev; /**< * chained list */
+                    struct fsm_log_unit_struct *prev; /**< * chained list */
-                    struct fsm_log_struct_unit *next; /**< * chained list */
+                    struct fsm_log_unit_struct *next; /**< * chained list */
                 }
-                fsm_log_struct_unit;
+                fsm_log_unit_struct;
 
 
 /**
- * Two links towards the previous and the next unit are required to initialize
+ * Log is a double-chained list. Two links towards the previous and the next unit
- * and manage a double-chained list.
+ * are required to initialize and manage it.
  *
  * @callgraph
  * @see fsm_log_struct_unit
@@ -222,8 +208,8 @@ typedef struct  fsm_log_struct_unit
  * @see fsm_remove_log()
  */
 typedef struct {
-                    fsm_log_struct_unit *first; /**< * required */
+                    fsm_log_unit_struct *first; /**< * required */
-                    fsm_log_struct_unit *last;  /**< * required */
+                    fsm_log_unit_struct *last;  /**< * required */
                }
                fsm_log_struct;
 
@@ -255,8 +241,8 @@ void fsm_add_log       (int severity,
                         const char *function_source,
                         const char *string_value);
 
-void fsm_trigger_log_init();
+void fsm_relay_init_log();
-void fsm_trigger_log_close();
+void fsm_relay_close_log();
 
 void fsm_init (const char *initial_message_from_main);
 void fsm_close (const char *final_message_from_main);

src/fsm/control.c

@@ -1,8 +1,9 @@
 /**
  * @file
- * Client fsm (Finite State Machine) control file.
+ * @brief This file is part of Gem-graph; it controls the client fsm
+ * (Finite State Machine).
  *
- * ---
+ * @details
  *
  * The fsm control instance
  * - **initialises** the log and the rest of the fsm when triggered by main()
@@ -10,35 +11,8 @@
  * - **closes** all the elements it opened before handing over to main()
  * .
  *
- * About code organization, see src/readme.dox
- *
  * ---
  *
- * @cond LICENSE
- * Copyright © 2021 Libre en Communs <contact@a-lec.org>
- * Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
- * Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
- *
- * This program is free software: you can redistribute it and/or modify it under
- * the terms of the GNU Affero General Public License as published by the Free
- * Software Foundation, either version 3 of the License, or (at your option) any
- * later version.
- *
- * This program is distributed in the hope that it will be useful, but WITHOUT
- * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
- * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
- * details.
- *
- * You should have received a copy of the GNU Affero General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- * @endcond
- *
- * @file
- * @brief
- *
- * This file is part of Gem-graph.
- *
- * @details
  * The Finite State Machine (fsm) describes all the possible states of the
  * Gem-graph client and all the transitions between them.
  * It manages several kinds of exclusive states:
@@ -64,6 +38,10 @@
  *
  * The journal is created, edited and published from here.
  *
+ * ---
+ *
+ * About code organization, see src/readme.dox
+ *
  * @cond LICENSE
  * Copyright © 2021 Libre en Communs <contact@a-lec.org>
  * Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
@@ -141,7 +119,10 @@ static void fsm_structures_close()
 
 /**
  * @brief fsm_init() is the first function called by main.c
- *        It initiates the journal and calls fsm_structures_init() that
+ * It initiates the journal and calls fsm_structures_init().
+ *
+ * It uses the relay function fsm_relay_init_log() in src/fsm/log/manager.c to
+ * reach the fsm_init_log().
  *
  * @since 2024-08
  *
@@ -149,7 +130,7 @@ static void fsm_structures_close()
  * @see main()
  *
  * @callgraph
- * @see trigger_fsm_log_init()
+ * @see fsm_relay_init_log()
  * @see fsm_add_log()
  * @see fsm_list_init_measures()
  * @see fsm_list_init_results()
@@ -160,9 +141,7 @@ static void fsm_structures_close()
  */
 void fsm_init (const char *initial_info_from_main)
 {
-    fsm_trigger_log_init(); /**< fsm_init_log(() can't be called from here
+    fsm_relay_init_log();
-                             * because static fsm_log_struct gg_logs
-                             * is in src/fsm/log/manager.c */
 
     fsm_add_log (INFO, MAIN, "main", initial_info_from_main,
                  "👋️ (☕️)  Hi everybody ! Here is Gem-Graph.");
@@ -194,7 +173,7 @@ void fsm_init (const char *initial_info_from_main)
  *
  * @callgraph
  * @see fsm_structures_close()
- * @see fsm_trigger_log_close()
+ * @see fsm_relay_close_log()
  * @see fsm_add_log()
  *
  * @param *closing_info_from_main
@@ -208,7 +187,7 @@ void fsm_close (const char *closing_info_from_main)
     fsm_add_log (INFO, MAIN, "main", closing_info_from_main,
                  "👋️😄️  That'all folks !");
 
-    fsm_trigger_log_close(); /**< fsm_clear_log(() can't be called from here
+    fsm_relay_close_log(); /**< fsm_clear_log(() can't be called from here
                              * because static fsm_log_struct gg_logs
                              * is in src/fsm/log/manager.c */
 }

src/fsm/log/appendix.c

@@ -1,8 +1,9 @@
 /**
  * @file
  *
- * This file is part of Gem-graph. The log (or journal) stores chronologically
+ * This file is part of Gem-graph; it contains only auxiliary functions.
- * the events during a session run   (rules exec, mainly)
+ *
+ * The log (or journal) stores chronologically the events during a session run.
  *
  * This file groups some functions that a typical list should implement but whose
  * utility remains to evaluate in the case of a log list.
@@ -50,7 +51,7 @@ long fsm_remove_log (fsm_log_struct *jj,
                      const char *string_value)
 {
     long usec;
-    fsm_log_struct_unit *tmp = jj->last;
+    fsm_log_unit_struct *tmp = jj->last;
     if (! tmp) return -1;
     usec = tmp->usec;
     jj->last = tmp->prev;
@@ -72,7 +73,7 @@ long fsm_remove_log (fsm_log_struct *jj,
  */
 int fsm_get_log_length (fsm_log_struct jj)
 {
-    fsm_log_struct_unit *a_unit = jj.first;
+    fsm_log_unit_struct *a_unit = jj.first;
     int nb = 0;
     while (a_unit)
     {
@@ -100,7 +101,7 @@ void fsm_seek_log (fsm_log_struct jj,
                    const char *function_source,
                    const char *string_value)
 {
-    fsm_log_struct_unit *a_unit = jj.first;
+    fsm_log_unit_struct *a_unit = jj.first;
     int nb = 0;
     while (a_unit)
     {

src/fsm/log/manager.c

@@ -1,14 +1,15 @@
 /**
  * @file
- * @brief fsm (Finite State Machine) log manager
+ * @brief This file is part of Gem-graph; fsm (Finite State Machine) log manager.
- *
- * This file is part of Gem-graph.
  *
  * @details
  * The log (journal) is created, edited and published from here.
- * This file contains only (1) the static fsm_log_struct gg_logs
+ *
- * and (2) the function fsm_add_log() that all calls must pass through to send a
+ * This file contains only
- * message to the log.
+ * -# the static fsm_log_struct **gg_logs**
+ * -# the function fsm_add_log() that all calls must pass through to send a
+ * message to the log and
+ * -# the two relay functions that init and publish the log before closing it.
  *
  * @cond LICENSE
  * Copyright © 2021 Libre en Communs <contact@a-lec.org>
@@ -38,33 +39,34 @@
 *******************************************************************************/
 
 /**
- * The fsm_struct_journal (gg_logs) is a static instance in the file
+ * The fsm_struct_journal (gg_logs) is a **static** instance in the file
  * /src/fsm/log/manager.c
- * Therefore, all the functions that read or write it are in this file.
+ * Therefore, all the functions that read or write it must be in the same file.
- * This helps to avoid uncontrolled operations.
+ *
+ * Limiting the access to gg_logs helps to avoid uncontrolled operations on it.
  */
 static fsm_log_struct gg_logs;
 
 
 /**
- * @brief It is mandatory for any event to call this function to be published in
+ * @brief To be published in the log, all events must pass through this function,
- * the journal.
+ * which enables filtering.
  *
- * @details The fsm_struct_journal (gg_logs) is a static instance in the file
+ * @details This function is both a relay and a filter.
- * /src/fsm/log/manager.c
- * Therefore, all the functions that read or write it will be in this file.
- * This is to avoid uncontrolled operations on it.
  *
- * A message is send to the log for each documented event.
+ * - It is a relay because it must call fsm_add_log_event() and pass it **gg_logs**
+ * to write to the log. As gg_logs is a **static** instance, this call can only
+ * be made from the same file.
  *
- * One or several filters can be applied here (and only here) before publication,
+ * - It's more than just a relay, because one or more filters can be applied here
- * to select only some events of interest (during debugging, for example).
+ * (and only here) before publication to select only certain events.
+ * The interest of events can vary according to the type of session.
  *
  * These filters can operate on any the following five parameters:
- * severity, source, file_source (text), function_source (text),
+ * - severity, - source, - file_source (text), - function_source (text),
- * string_value (text).
+ * - string_value (text).
  *
- * They can be combined using any logical operators and parentheses.
+ * The filters can be combined using any logical operators and parentheses.
  *
  * @since 2024-08
  *
@@ -102,11 +104,15 @@ void fsm_add_log (int severity,
     fsm_add_log_event (&gg_logs, file_source, function_source, string_value);
 }
 
+
 /**
- * this function is a relay: fsm_init_log() can't be called directly from
+ * This function is only a relay: it calls fsm_init_log() and this call couldn't
- * fsm_init() in control because static fsm_log_struct gg_logs is in
+ * be written in another file because the fsm_log_struct **gg_logs** it transmits
- * src/fsm/log/manager.c
+ * is **static** in src/fsm/log/manager.c
  *
+ * Limiting the access to **gg_logs** helps to avoid uncontrolled operations on it.
+ *
+ * Functions which only relay should not send log.
  *
  * @since 2024-08
  *
@@ -114,15 +120,20 @@ void fsm_add_log (int severity,
  * @see main()
  *
  */
-void fsm_trigger_log_init()
+void fsm_relay_init_log()
 {
     fsm_init_log (&gg_logs);
 }
 
+
 /**
- * this function is a relay: fsm_publish_log() and fsm_clear_log() can't be
+ * This function is only a relay: it calls fsm_publish_log() and fsm_clear_log()
- * called directly from fsm_close() in control because static fsm_log_struct
+ * and this calls couldn't be written in another file because the fsm_log_struct
- * gg_logs is in src/fsm/log/manager.c
+ * **gg_logs** they transmit is **static** in src/fsm/log/manager.c
+ *
+ * Limiting the access to **gg_logs** helps to avoid uncontrolled operations on it.
+ *
+ * Functions which only relay should not send log.
  *
  * @since 2024-08
  *
@@ -130,7 +141,7 @@ void fsm_trigger_log_init()
  * @see main()
  *
  */
-void fsm_trigger_log_close()
+void fsm_relay_close_log()
 {
     fsm_publish_log (gg_logs);
     fsm_clear_log (&gg_logs);

src/fsm/log/oper.c

@@ -68,8 +68,8 @@ void fsm_init_log (fsm_log_struct *jj)
  */
 void fsm_clear_log (fsm_log_struct *jj)
 {
-   fsm_log_struct_unit *tmp;
+   fsm_log_unit_struct *tmp;
-   fsm_log_struct_unit *a_unit = jj->first;
+   fsm_log_unit_struct *a_unit = jj->first;
    while(a_unit)
    {
      tmp = a_unit;
@@ -84,7 +84,7 @@ void fsm_clear_log (fsm_log_struct *jj)
 /**
  * add an event
  *
- * *new_unit = malloc (sizeof(fsm_log_struct_unit));
+ * *new_unit = malloc (sizeof(fsm_log_unit_struct));
  *
  * warn: is never free (as new log units are never removed)
  *
@@ -102,7 +102,7 @@ void fsm_add_log_event (fsm_log_struct *jj,
 {
     struct timeval tv;
     gettimeofday (&tv, NULL);
-    fsm_log_struct_unit *new_unit = malloc (sizeof(fsm_log_struct_unit));
+    fsm_log_unit_struct *new_unit = malloc (sizeof(fsm_log_unit_struct));
     if (! new_unit) exit (EXIT_FAILURE);
 
     new_unit->yy_dd_mm = tv.tv_sec;
@@ -132,7 +132,7 @@ void fsm_add_log_event (fsm_log_struct *jj,
  */
 void fsm_publish_log (fsm_log_struct jj)
 {
-    fsm_log_struct_unit *a_unit = jj.last;
+    fsm_log_unit_struct *a_unit = jj.last;
     char buf [LOG_MAX_LENGTH];
     int nb = 0;
     while (a_unit)