From 862b316526097c1238c112b34c3407151a465b75 Mon Sep 17 00:00:00 2001 From: Jean Sirmai Date: Tue, 15 Oct 2024 15:33:53 +0200 Subject: [PATCH] cleaning under doxygen control: replacing phantoms comments in main and fsm/dispatch is effective --- doc/(pesonnal notes) | 23 +++++++++++++++++++ doc/Doxyfile | 2 +- doc/Readme | 2 +- src/fsm/dispatch.c | 53 +++++++++++--------------------------------- src/main.c | 35 +++++------------------------ 5 files changed, 44 insertions(+), 71 deletions(-) diff --git a/doc/(pesonnal notes) b/doc/(pesonnal notes) index 52e4bda..89e58c7 100644 --- a/doc/(pesonnal notes) +++ b/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 diff --git a/doc/Doxyfile b/doc/Doxyfile index b8be0b1..6ef163f 100644 --- a/doc/Doxyfile +++ b/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 diff --git a/doc/Readme b/doc/Readme index 4815ef8..bb45864 100644 --- a/doc/Readme +++ b/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' <<<<<<<<<< -------------------------------------------------------------------------------- diff --git a/src/fsm/dispatch.c b/src/fsm/dispatch.c index 3237d0a..beefebf 100644 --- a/src/fsm/dispatch.c +++ b/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 const char *function_source <> the function that emits the event. - * @param const char *string_value <> any value that can qualify the event + * @param *file_source <> the name of the file that emits the event. + * @param *function_source <> the function that emits 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 - * @return void + * @param *initial_message_from_main */ 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. - * @return void + * @param value = TRUE if preferences_have_been_modified. */ 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" - * @return void + * @param choice < a boolean value which can be "EXEC" or "EDIT" */ 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 - * @return void + * @param choice */ void fsm_set_state_rules_data (int choice) { diff --git a/src/main.c b/src/main.c index 9268b1f..3549480 100644 --- a/src/main.c +++ b/src/main.c @@ -115,22 +115,21 @@ #include "../include/fsm.h" /** - * @brief gem-graph-client main - * @details (none) - * @dir /src/ - * @file main.c + * @brief gem-graph-client main() + * * @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; }