From 134a02cb62088f2593b66fbd7296a861fc0a0bd4 Mon Sep 17 00:00:00 2001 From: Jean Sirmai Date: Tue, 15 Oct 2024 08:55:07 +0200 Subject: [PATCH] cleaning under doxygen control: replacing phantoms comments in main and fsm/dispatch --- doc/(pesonnal notes) | 5 + doc/Readme | 8 +- include/fsm.h | 2 + src/fsm/dispatch.c | 257 ++++++++++++++++++++++++++++++++++++++----- src/main.c | 17 ++- to_delete | 10 ++ 6 files changed, 269 insertions(+), 30 deletions(-) create mode 100644 to_delete diff --git a/doc/(pesonnal notes) b/doc/(pesonnal notes) index 252dd79..52e4bda 100644 --- a/doc/(pesonnal notes) +++ b/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 diff --git a/doc/Readme b/doc/Readme index edc9090..4815ef8 100644 --- a/doc/Readme +++ b/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 's/phantom documentation used to test the functioning of doxygen/\n +sed -i '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' <<<<<<<<<< + -------------------------------------------------------------------------------- diff --git a/include/fsm.h b/include/fsm.h index a312d21..027a9ba 100644 --- a/include/fsm.h +++ b/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. * * - - - - - - - - - - - - - - - - - - - - - - - - - - * diff --git a/src/fsm/dispatch.c b/src/fsm/dispatch.c index 10db15f..3237d0a 100644 --- a/src/fsm/dispatch.c +++ b/src/fsm/dispatch.c @@ -52,17 +52,22 @@ * and all the transitions between these states. * * @details gem-graph-client fsm (Finite State Machine) manages the four topics: - * - engine (window appearance) - * - measures (current measurements) - * - results (current data acquisition and displays) - * - preferences (current user preferences) + * - engine (window appearance) + * - measures (current measurements) + * - 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 */ - -// CRITICAL ERROR WARNING INFO MESSAGE DEBUG SPEW -// 0 1 2 3 4 5 6 +/** + * @brief It is mandatory for an event to call this function + * to be published in the journal. + * 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 */ - -// preferences_have_been_modified -// and should be stored before closing the current session. TODO +/** + * @brief getter for the static boolean: 'preferences_have_been_modified' + * + * @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) diff --git a/src/main.c b/src/main.c index f54e4a6..9268b1f 100644 --- a/src/main.c +++ b/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) { diff --git a/to_delete b/to_delete new file mode 100644 index 0000000..409266f --- /dev/null +++ b/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