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

doc/(pesonnal notes)

@@ -1,8 +1,31 @@
 https://thevaluable.dev/sed-cli-practical-guide-examples/#the-basics-of-sed
 
 
+********************************************************************************
 
 
+/*
+    printf("voir à la fin de 'main: étude des limites de la fonction 'snprintf()'\n");
+
+    long num = 1234567891234567891;
+    char str[20];
+
+    sprintf(str, "%ld", num); // integer to string
+    printf("sprintf  %ld  >  str %s\n", num, str);
+
+    snprintf(str, sizeof(str), "%ld", num);
+    printf("snprintf %ld  >  str %s\n", num, str);
+
+    strtol(str, NULL, 0); // The strtol() function takes a char pointer as its first argument, followed by two ints.
+                          // The first int specifies the base of the number,
+                          // and the second int specifies the maximum number of characters to be converted.
+    printf("strtol   %ld  >  str %s\n", num, str);
+*/
+
+
+
+********************************************************************************
+
 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/Doxyfile

@@ -209,7 +209,7 @@ SHORT_NAMES            = NO
 # description.)
 # The default value is: NO.
 
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
 
 # If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line
 # such as

doc/Readme

@@ -70,7 +70,7 @@ sed -i 's/phantom documentation used to test the functioning of doxygen/\n
 * @callgraph \n * @see \n * @callergraph \n * @see\n * @param \n * @return \n/'
 ./src/main.c   <  or any other file...
 
-NB  signal et journal n'ont pasétés 'tagés'  <<<<<<<<<<
+NB  signal et journal n'ont pas été 'tagués'  <<<<<<<<<<
 
 --------------------------------------------------------------------------------
 

src/fsm/dispatch.c

@@ -88,8 +88,6 @@ static fsm_struct_journal gg_logs;
  *        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
  *
@@ -97,9 +95,6 @@ static fsm_struct_journal gg_logs;
  * @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);}
 
@@ -111,14 +106,15 @@ void fsm_journal_publication_request() {fsm_journal_publish (gg_logs);}
  *
  * @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:
+ *
+ *        This 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
  *
@@ -145,22 +141,20 @@ void fsm_journal_publication_request() {fsm_journal_publish (gg_logs);}
  * @see src/util/tree.c
  * @see src/signal.c * 38
  *
- * @param int severity  <>  see enum fsm_enum_journal_severity in include/fsm.h
+ * @param 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
+ * @param 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 *file_source  <>  the name of the file that emits the event.
- * @param const char *function_source  <>  the function that emits the event.
+ * @param *function_source  <>  the function that emits the event.
- * @param const char *string_value  <>  any value that can qualify the event
+ * @param *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,
@@ -187,8 +181,6 @@ void fsm_journal_event (int severity,
  *        '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
  *
@@ -202,8 +194,7 @@ void fsm_journal_event (int severity,
  * @see src/fsm/preferences/manager/fsm_list_init_displayables()
  * @see src/fsm/preferences/manager/fsm_list_init_preferences()
  *
- * @param char *initial_message_from_main
+ * @param *initial_message_from_main
- * @return void
  */
 void fsm_init (char *initial_message_from_main)
 {
@@ -250,8 +241,6 @@ static int preferences_have_been_modified = FALSE;
 /**
  * @brief setter for the static boolean: 'preferences_have_been_modified'
  *
- * @dir src/fsm/
- * @file dispatch.c
  * @date 2024-08
  * @author Jean
  *
@@ -260,8 +249,7 @@ static int preferences_have_been_modified = FALSE;
  * @callergraph
  * @see fsm_journal_event()
  *
- * @param bool value = TRUE if preferences_have_been_modified.
+ * @param value = TRUE if preferences_have_been_modified.
- * @return void
  */
 void  fsm_set_preferences_modified (bool value)
 {
@@ -280,8 +268,6 @@ void  fsm_set_preferences_modified (bool value)
 /**
  * @brief getter for the static boolean: 'preferences_have_been_modified'
  *
- * @dir src/fsm/
- * @file dispatch.c
  * @date 2024-08
  * @author Jean
  *
@@ -291,7 +277,6 @@ void  fsm_set_preferences_modified (bool value)
  * @callergraph
  * @see (none)
  *
- * @param (none)
  * @return preferences_have_been_modified
  */
 bool  fsm_get_preferences_state() {return preferences_have_been_modified;}
@@ -308,8 +293,6 @@ static int choice_STATE_RULES_DATA = SYNTH; // THE FIRST PAGE TO BE PRESENTED
  * @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
  *
@@ -320,7 +303,6 @@ static int choice_STATE_RULES_DATA = SYNTH; // THE FIRST PAGE TO BE PRESENTED
  * @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;}
@@ -332,8 +314,6 @@ int  fsm_get_exec_edit() {return choice_EXEC_EDIT;}
  * @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
  *
@@ -343,7 +323,6 @@ int  fsm_get_exec_edit() {return choice_EXEC_EDIT;}
  * @callergraph
  * @see (none)
  *
- * @param (none)
  * @return choice_STATE_RULES_DATA
  */
 int  fsm_get_state_rules_data() {return choice_STATE_RULES_DATA;}
@@ -362,8 +341,6 @@ static char *tab_1 [] = { "SYNTH", "STATE", "RULES", "RESULTS" };
  * @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
  *
@@ -372,8 +349,7 @@ static char *tab_1 [] = { "SYNTH", "STATE", "RULES", "RESULTS" };
  * @callergraph
  * @see src/signal * 2
  *
- * @param int choice  <  a boolean value which can be "EXEC" or "EDIT"
+ * @param choice  <  a boolean value which can be "EXEC" or "EDIT"
- * @return void
  */
 void fsm_set_exec_edit (int choice)
 {
@@ -395,8 +371,6 @@ void fsm_set_exec_edit (int choice)
  *          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
  *
@@ -405,8 +379,7 @@ void fsm_set_exec_edit (int choice)
  * @callergraph
  * @see (none)
  *
- * @param int choice
+ * @param choice
- * @return void
  */
 void fsm_set_state_rules_data (int choice)
 {

src/main.c

@@ -115,22 +115,21 @@
 #include "../include/fsm.h"
 
 /**
- * @brief gem-graph-client main
+ * @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
+ * @param argc
+ * @param **argv
  * @return status
  */
-
 int main (int argc, char **argv)
 {
      //   def: src/fsm/dispatch      fsm = finite state machine
@@ -156,28 +155,6 @@ int main (int argc, char **argv)
     fsm_journal_event (INFO, MAIN, "main", "That'all folks !", "👋️😄️");
     fsm_journal_publication_request();
 
-
-
-/*
-    printf("voir à la fin de 'main: étude des limites de la fonction 'snprintf()'\n");
-
-    long num = 1234567891234567891;
-    char str[20];
-
-    sprintf(str, "%ld", num); // integer to string
-    printf("sprintf  %ld  >  str %s\n", num, str);
-
-    snprintf(str, sizeof(str), "%ld", num);
-    printf("snprintf %ld  >  str %s\n", num, str);
-
-    strtol(str, NULL, 0); // The strtol() function takes a char pointer as its first argument, followed by two ints.
-                          // The first int specifies the base of the number,
-                          // and the second int specifies the maximum number of characters to be converted.
-    printf("strtol   %ld  >  str %s\n", num, str);
-*/
-
-
-
     return status;
 }