gem-graph/gem-graph-client
gem-graph
/
gem-graph-client
3
0
Fork 0
Code Issues 14 Pull Requests Projects Releases Activity

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

This commit is contained in:
Jean Sirmai 2024-10-15 08:55:07 +02:00
parent 18473f6f53
commit 134a02cb62
Signed by: jean
GPG Key ID: FB3115C340E057E3
6 changed files with 269 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/(pesonnal notes)
View File

@ -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

8
doc/Readme
View File

@ -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' <<<<<<<<<<
--------------------------------------------------------------------------------

2
include/fsm.h
View File

@ -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.
*
* - - - - - - - - - - - - - - - - - - - - - - - - - -
*

257
src/fsm/dispatch.c
View File

@ -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)

17
src/main.c
View File

@ -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)
{

10
to_delete Normal file
View File

@ -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