cleaning under doxygen control: replacing phantoms comments in main and fsm/dispatch

doc/(pesonnal notes)

@@ -1,3 +1,8 @@
+https://thevaluable.dev/sed-cli-practical-guide-examples/#the-basics-of-sed
+
+
+
+
 pour les menus:
 https://discourse.gnome.org/t/when-do-we-really-have-to-use-gtk-popover-present-to-show-a-popover-at-a-given-widget/17566/5
 https://stackoverflow.com/questions/69135934/creating-a-simple-menubar-menu-and-menu-item-in-c-using-gtk4

doc/Readme

@@ -65,11 +65,13 @@ qui remplacera tous les commentaires 'fantômes':
 /**< a_variable_name           phantom documentation */
 
 
-echo phantom documentation used to test the functioning of doxygen |
+sed -i 's/phantom documentation used to test the functioning of doxygen/\n
-sed 's/phantom documentation used to test the functioning of doxygen/\n
 * @brief \n * @details \n * @dir \n * @file \n * @date \n * @author \n
 * @callgraph \n * @see \n * @callergraph \n * @see\n * @param \n * @return \n/'
-./src/main.c > ./to_delete
+./src/main.c   <  or any other file...
+
+NB  signal et journal n'ont pasétés 'tagés'  <<<<<<<<<<
+
 --------------------------------------------------------------------------------
 
 

include/fsm.h

@@ -43,6 +43,8 @@
 * - fonction
 * - valeur, paramètre, descriptif, contexte,...
 *   (tout ce qui peut contribuer à améliorer la compréhension du journal)
+ *  any value that can qualify the event
+ *  and provides useful information when reading the log.
 *
 *  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
 *

src/fsm/dispatch.c

@@ -57,12 +57,17 @@
  *           - results       (current data acquisition and displays)
  *           - preferences   (current user preferences)
  *
- *          Each state of the finite state machine (fsm) must be
+ *           Each state of the finite state machine (fsm)
+ *           is a combination of their states.
+ *
+ *           It must be
  *             - saved at the end of a work session and
  *             - reread (available) at the start of a new session.
  *
  *           No state of the fsm should be defined  in another module.
  *           No fsm transition needs to be executed in another module.
+ *
+ *           The journal is created, edited and published from here.
  */
 
 
@@ -72,14 +77,91 @@
 
 static fsm_struct_journal gg_logs;
 
-/** phantom documentation used to test the functioning of doxygen */
+/**
-
+ * @brief The log is modified for each event but is only published once, before
+ *        the end of "main()", in order to guarantee its chronological order.
+ *
+ * @details The fsm_journal_publication_request() is called only once,
+ *        by 'main.c' just before ending and returning its status.
+ *        Therefore, src/journal.c/fsm_journal_publish() (called here)
+ *        is the last function of the program to be executed.
+ *        Also, it is safer to keep only one static instance
+ *        of the fsm_struct_journal here to avoid uncontrolled operations on it.
+ *
+ * @dir src/fsm/
+ * @file dispatch.c
+ * @date 2024-08
+ * @author Jean
+ *
+ * @callgraph
+ * @see src/main/main()
+ * @callergraph
+ * @see src/journal/fsm_journal_publish()
+ *
+ * @param (none)
+ * @return (void)
+ */
 void fsm_journal_publication_request() {fsm_journal_publish (gg_logs);}
 
-/** phantom documentation used to test the functioning of doxygen */
+/**
-
+ * @brief It is mandatory for an event to call this function
-//   CRITICAL   ERROR    WARNING   INFO   MESSAGE   DEBUG    SPEW
+ *        to be published in the journal.
-//      0         1         2        3       4        5        6
+ *        Before publication, a filter can be applied here (and only here)
+ *        to select only some events of interest (during debugging, for example).
+ *
+ * @details  If there are too many events, a filter can be applied here
+ *        to select a few interesting events for publication in the log.
+ *        A filter can operate on any the following five parameters:
+ *        severity, source, *file_source, *function_source, *string_value.
+ *        Simple filters (on a single parameter) can be combined
+ *        using the logical operators 'and' and 'or' and parentheses.
+ *        Use: $ grep -r "fsm_journal_event" to confirm the callergraph calls.
+ *
+ * @dir src/fsm/
+ * @file dispatch.c
+ * @date 2024-08
+ * @author Jean
+ *
+ * @callgraph
+ * @see src/journal.c/fsm_journal_push_front()
+ *
+ * @callergraph
+ * @see src/main/main()
+ * @see src/widget/topbar/modal.c
+ * @see src/widget/topbar/right.c
+ * @see src/widget/topbar/dialog.c
+ * @see src/widget/topbar/left.c
+ * @see src/widget/topbar/dispatch.c * 3
+ * @see src/widget/one_rule/dispatch.c
+ * @see src/widget/one_rule/algebra/conditions.c * 2
+ * @see src/widget/measure/dispatch.c
+ * @see src/widget/dispatch.c * 3
+ * @see src/widget/all_rules/dispatch.c
+ * @see src/fsm/preferences/manager.c * 8
+ * @see src/fsm/measures/manager.c * 2
+ * @see src/fsm/measures/tools_list.c * 4
+ * @see src/fsm/dispatch.c * 10
+ * @see src/fsm/results/manager.c
+ * @see src/util/tree.c
+ * @see src/signal.c * 38
+ *
+ * @param int severity  <>  see enum fsm_enum_journal_severity in include/fsm.h
+ *        'severity' is a pre-defined value that must be associated to each event.
+ *        It ranges from zero to six :
+ *        CRITICAL   ERROR    WARNING   INFO   MESSAGE   DEBUG    SPEW
+ *           0         1         2        3       4        5        6
+ *
+ * @param int source  <>  see enum fsm_enum_journal_source in include/fsm.h
+ *        'source'  is a pre-defined value that can be associated to each event.
+ *        It is not mandatory. It can be set to 'NULL'.
+ *
+ * @param const char *file_source  <>  the name of the file that emits the event.
+ * @param const char *function_source  <>  the function that emits the event.
+ * @param const char *string_value  <>  any value that can qualify the event
+ *        and provides useful information when reading the log.
+ *
+ * @return void
+ */
 void fsm_journal_event (int severity,
                         int source,
                         const char *file_source,
@@ -99,8 +181,30 @@ void fsm_journal_event (int severity,
  *                           F S M   I N I T                                   *
 *******************************************************************************/
 
-/** phantom documentation used to test the functioning of doxygen */
+/**
-
+ * @brief This is the first function called by 'main.c'
+ *        It initiates the journal and the lists of:
+ *        'measures', 'results', 'displayables results' and 'preferences'.
+ *        These lists will be used to define the current state of the fsm.
+ *
+ * @dir src/fsm/
+ * @file dispatch.c
+ * @date 2024-08
+ * @author Jean
+ *
+ * @callgraph
+ * @see src/main/main()
+ * @callergraph
+ * @see src/journal/fsm_journal_init()
+ * @see src/fsm/dispatch/fsm_journal_event()
+ * @see src/fsm/measures/manager/fsm_list_init_measures()
+ * @see src/fsm/results/manager/fsm_list_init_results()
+ * @see src/fsm/preferences/manager/fsm_list_init_displayables()
+ * @see src/fsm/preferences/manager/fsm_list_init_preferences()
+ *
+ * @param char *initial_message_from_main
+ * @return void
+ */
 void fsm_init (char *initial_message_from_main)
 {
     fsm_journal_init (&gg_logs);
@@ -143,8 +247,22 @@ void fsm_init (char *initial_message_from_main)
 
 static int preferences_have_been_modified = FALSE;
 
-/** phantom documentation used to test the functioning of doxygen */
+/**
-
+ * @brief setter for the static boolean: 'preferences_have_been_modified'
+ *
+ * @dir src/fsm/
+ * @file dispatch.c
+ * @date 2024-08
+ * @author Jean
+ *
+ * @callgraph
+ * @see TODO To be used by any function that modifies the current user preferences
+ * @callergraph
+ * @see fsm_journal_event()
+ *
+ * @param bool value = TRUE if preferences_have_been_modified.
+ * @return void
+ */
 void  fsm_set_preferences_modified (bool value)
 {
     const char *str_value;
@@ -159,10 +277,23 @@ void  fsm_set_preferences_modified (bool value)
 }
 
 
-/** phantom documentation used to test the functioning of doxygen */
+/**
-
+ * @brief getter for the static boolean: 'preferences_have_been_modified'
-//    preferences_have_been_modified
+ *
-//    and should be stored before closing the current session.   TODO
+ * @dir src/fsm/
+ * @file dispatch.c
+ * @date 2024-08
+ * @author Jean
+ *
+ * @callgraph
+ * @see TODO A function must obtain this boolean when it stores the current state
+ *           of the fsm (including preferences) before closing the current session.
+ * @callergraph
+ * @see (none)
+ *
+ * @param (none)
+ * @return preferences_have_been_modified
+ */
 bool  fsm_get_preferences_state() {return preferences_have_been_modified;}
 
 
@@ -171,13 +302,50 @@ static int choice_STATE_RULES_DATA = SYNTH; // THE FIRST PAGE TO BE PRESENTED
            //   SEE ALSO   fsm/dispatch.c  window_design_topbar_left() (the end)
 
 
-/** phantom documentation used to test the functioning of doxygen */
+/**
-
+ * @brief Any function that modifies the client window must obtain this boolean.
+ *        The 'state' and 'rules' pages appearance depends heavily on this.
+ * @details see include/fsm enum fsm_enum_exec_edit { EXEC, EDIT }
+ *          The current int may be replaced by a boolean before publication. TODO
+ *
+ * @dir src/fsm/
+ * @file dispatch.c
+ * @date 2024-08
+ * @author Jean
+ *
+ * @callgraph
+ * @see src/widget/one_rule/dispatch
+ * @see src/widget/state/dispatch * 2
+ * @see src/signal
+ * @callergraph
+ * @see  include/fsm enum fsm_enum_exec_edit { EXEC, EDIT }  <<  TODO check this
+ *
+ * @param (none)
+ * @return choice_EXEC_EDIT
+ */
 int  fsm_get_exec_edit() {return choice_EXEC_EDIT;}
 
 
-/** phantom documentation used to test the functioning of doxygen */
+/**
-
+ * @brief Any function that modifies the client window must obtain this value.
+ *        The pages selection and the window appearance depends heavily on this.
+ * @details see include/fsm enum
+ *          fsm_enum_state_rules_data { SYNTH, STATE, RULES, DATA }
+ *
+ * @dir src/fsm/
+ * @file dispatch.c
+ * @date 2024-08
+ * @author Jean
+ *
+ * @callgraph
+ * @see src/widget/topbar/left
+ * @see src/signal
+ * @callergraph
+ * @see (none)
+ *
+ * @param (none)
+ * @return choice_STATE_RULES_DATA
+ */
 int  fsm_get_state_rules_data() {return choice_STATE_RULES_DATA;}
 
 
@@ -189,8 +357,24 @@ int  fsm_get_state_rules_data() {return choice_STATE_RULES_DATA;}
 static char *tab_0 [] = { "EXEC", "EDIT" };
 static char *tab_1 [] = { "SYNTH", "STATE", "RULES", "RESULTS" };
 
-/** phantom documentation used to test the functioning of doxygen */
 
+/**
+ * @brief setter for the static value: 'choice_STATE_RULES_DATA'
+ * @details see include/fsm enum fsm_enum_exec_edit { EXEC, EDIT }
+ *
+ * @dir src/fsm/
+ * @file dispatch.c
+ * @date 2024-08
+ * @author Jean
+ *
+ * @callgraph
+ * @see (none)
+ * @callergraph
+ * @see src/signal * 2
+ *
+ * @param int choice  <  a boolean value which can be "EXEC" or "EDIT"
+ * @return void
+ */
 void fsm_set_exec_edit (int choice)
 {
     if (choice_EXEC_EDIT != choice)
@@ -201,8 +385,29 @@ void fsm_set_exec_edit (int choice)
     }
 }
 
-/** phantom documentation used to test the functioning of doxygen */
+/**
-
+ * @brief setter for the static value: 'choice_STATE_RULES_DATA'
+ *
+ * @details see include/fsm enum
+ *          fsm_enum_state_rules_data { SYNTH, STATE, RULES, DATA }
+ *          Today (2024-10) the initial page is set to 'SYNTH'.
+ * @see     line 292      choice_STATE_RULES_DATA = SYNTH;
+ *          NB  This choice can be temporarily modified for debugging purpose:
+ * @see     end of the function: fsm/dispatch.c  window_design_topbar_left()
+ *
+ * @dir src/fsm/
+ * @file dispatch.c
+ * @date 2024-08
+ * @author Jean
+ *
+ * @callgraph
+ * @see src/signal * 4
+ * @callergraph
+ * @see (none)
+ *
+ * @param int choice
+ * @return void
+ */
 void fsm_set_state_rules_data (int choice)
 {
     if (choice_STATE_RULES_DATA != choice)

src/main.c

@@ -114,7 +114,22 @@
 #include "../include/signal.h"
 #include "../include/fsm.h"
 
-/** phantom documentation used to test the functioning of doxygen */
+/**
+ * @brief gem-graph-client main
+ * @details (none)
+ * @dir /src/
+ * @file main.c
+ * @date 2024-04
+ * @author Jean
+ * @callgraph
+ * @see src/fsm/dispatch
+ * @see src/signal
+ * @callergraph
+ * @see (none)
+ * @param int argc
+ * @param char **argv
+ * @return status
+ */
 
 int main (int argc, char **argv)
 {

to_delete

@@ -0,0 +1,10 @@
+./src/widget/dispatch.c
+./src/widget/all_rules/compare/interest.c
+./src/fsm/preferences/manager.c
+./src/util/draw/gl.c
+./doc/Readme
+./include/widget.h
+./include/base.h
+./include/graphics.h
+./include/util.h
+./include/fsm.h