docs/doxyfile,html,rtfm/man3/*, Makefile: integrate doxygen for documentation
We wanted to have an automated documentation for our project. We choose doxygen since this is a well-established project, with common standards. To generate the documentation, simply type `make docs` and open `docs/html/index.html`. TODO: properly document the whole project.
This commit is contained in:
parent
43ddfad3af
commit
73c474b765
GPG Key ID:
FB3115C340E057E3
|
|
@ -1,3 +1,5 @@
|
|||
bin/*
|
||||
build/*
|
||||
docs/html/*
|
||||
docs/rtfm/man3/*
|
||||
scripts/junk
|
||||
8
Makefile
8
Makefile
|
|
@ -1,4 +1,4 @@
|
|||
.PHONY: run clean install all
|
||||
.PHONY: run clean install all docs
|
||||
.DELETE_ON_ERROR: $(BINDIR)/Getting_Started_with_GTK
|
||||
.DEFAULT_GOAL: all
|
||||
|
||||
|
|
@ -6,6 +6,7 @@ CPUS ?= $(shell (nproc --all || sysctl -n hw.ncpu) 2>/dev/null || echo 1)
|
|||
MAKEFLAGS += --jobs=$(CPUS)
|
||||
|
||||
CC=gcc
|
||||
DOXYGEN=doxygen
|
||||
CFLAGS=`pkg-config --cflags gtk4 epoxy glib-2.0 libxml-2.0`
|
||||
LDFLAGS=`pkg-config --libs gtk4 epoxy glib-2.0 libxml-2.0` -lGL -lGLU -lm -lepoxy -lX11 -lGLEW
|
||||
WARNINGS = -Wall
|
||||
|
|
@ -15,6 +16,7 @@ OPTIMIZE = -O3
|
|||
BINDIR=bin
|
||||
BUILDDIR=build
|
||||
SRCDIR=src
|
||||
DOCSDIR=docs
|
||||
|
||||
SOURCES = $(shell find $(SRCDIR) -type f -name "*.c")
|
||||
OBJECTS = $(patsubst %.c,$(BUILDDIR)/%.o,$(SOURCES))
|
||||
|
|
@ -69,6 +71,10 @@ install:
|
|||
run: $(BINDIR)/gem-graph-client
|
||||
$(BINDIR)/gem-graph-client
|
||||
|
||||
docs: $(SOURCES) $(DEPENDENCIES)
|
||||
@$(DOXYGEN) $(DOCSDIR)/doxyfile
|
||||
@echo " DOXYGEN $(DOCSDIR)/doxyfile"
|
||||
|
||||
clean:
|
||||
@rm -rf $(BINDIR)
|
||||
@echo " RM $(BINDIR)"
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
Binary file not shown.
|
After Width: | Height: | Size: 3.4 KiB |
|
|
@ -0,0 +1,385 @@
|
|||
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
||||
* Gem-graph client *
|
||||
* What the documentation contains and how to use it *
|
||||
* Docstring content: rationale and usage *
|
||||
* Alphabetic Index 2024 of functions names *
|
||||
* *
|
||||
* Copyright © 2021 Libre en Communs <contact@a-lec.org> *
|
||||
* Copyright © 2024 Jean Sirmai <jean@a-lec.org> *
|
||||
* *
|
||||
* This file is part of Gem-graph. *
|
||||
* *
|
||||
* This program is free software: you can redistribute it and/or modify it *
|
||||
* under the terms of the GNU Affero General Public License *
|
||||
* as publishedby the Free Software Foundation, *
|
||||
* either version 3 of the License, or (at your option) any later version. *
|
||||
* *
|
||||
* This program is distributed in the hope that it will be useful, *
|
||||
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
|
||||
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. *
|
||||
* See the GNU Affero General Public License for more details. *
|
||||
* *
|
||||
* You should have received a copy of the GNU Affero General Public License *
|
||||
* along with this program. If not, see <http://www.gnu.org/licenses/>. *
|
||||
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
||||
|
||||
Attention
|
||||
Let's repeat that, because it is often overlooked:
|
||||
to document global objects (functions, typedefs, enum, macros, etc),
|
||||
you must document the file in which they are defined.
|
||||
In other words, there must at least be a
|
||||
/** \file */
|
||||
(or /*! \file */)
|
||||
line in this file.
|
||||
|
||||
---------------------------------------------------------------------------
|
||||
*
|
||||
* docstrings
|
||||
* ----------
|
||||
* Pour chaque fonction, quelles sont les infos prioritaires ?
|
||||
*
|
||||
* @brief
|
||||
* @details
|
||||
* @date
|
||||
* @author
|
||||
* @callgraph
|
||||
* @see (liste des fonctions appelées par cette fonction)
|
||||
* @callergraph
|
||||
* @see (liste des fonctions qui appellent cette fonction)
|
||||
* @param (liste des paramètres)
|
||||
* @return
|
||||
|
||||
autres (à envisager) @see https://www.doxygen.nl/manual/commands.html
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
git commit 2024-10-14 avant d'exécuter une commande sed
|
||||
qui remplacera tous les commentaires 'fantômes':
|
||||
/** phantom documentation used to test the functioning of doxygen */
|
||||
/**< a_variable_name phantom documentation */
|
||||
|
||||
|
||||
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 < or any other file...
|
||||
|
||||
NB signal et journal n'ont pas été 'tagués' <<<<<<<<<<
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
|
||||
*
|
||||
*
|
||||
* TODO : actuellement, valgrind bin/gem-graph-client détecte :
|
||||
*
|
||||
* HEAP SUMMARY:
|
||||
* in use at exit: 11,537,505 bytes in 42,285 blocks
|
||||
* total heap usage: 483,548 allocs,
|
||||
* 441,263 frees,
|
||||
* 112,049,363 bytes allocated
|
||||
* LEAK SUMMARY:
|
||||
* definitely lost: 40,161 bytes in 79 blocks
|
||||
* indirectly lost: 11,233 bytes in 489 blocks
|
||||
* possibly lost: 7,879,639 bytes in 7,844 blocks
|
||||
* still reachable: 3,412,408 bytes in 32,248 blocks
|
||||
* suppressed: 0 bytes in 0 blocks
|
||||
* Rerun with --leak-check=full to see details of leaked memory
|
||||
*
|
||||
* valgrind --leak-check=full > ERROR SUMMARY: 1572 errors from 680 contexts
|
||||
* --track-origins=yes ERROR SUMMARY: 896 errors from 4 contexts
|
||||
* --show-leak-kinds=all
|
||||
*
|
||||
* sanitize <<
|
||||
*
|
||||
*
|
||||
* TODO des scripts devraient pouvoir recueillir ces informations
|
||||
* pour produire automatiquement, à la demande, des listes comme celle qui suit.
|
||||
* (voir le dossier 'scripts')
|
||||
* > plutôt utiliser Doxygen.
|
||||
*
|
||||
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
/* * * * * * * * * * * * * * * * * * * * * * * * * * *
|
||||
*
|
||||
* C O N V E N T I O N S E T R È G L E S D E N O M M A G E - 2 0 2 4
|
||||
*
|
||||
* Le nom d'une fonction doit permettre d'identifier facilement:
|
||||
* - le lieu (le fichier) où elle est définie,
|
||||
* - le type d'action qu'elle exécute et
|
||||
* - les objets modifiés par son action.
|
||||
*
|
||||
* - - -
|
||||
*
|
||||
* Ces trois informations sont encodées au moyen de trois "préfixes"
|
||||
* associés et concaténés dans cet ordre pour former le nom.
|
||||
*
|
||||
* - - -
|
||||
*
|
||||
* En octobre 2024, la première version de cet:
|
||||
* "index alphabétique des fonctiond du client gem-graph"
|
||||
* classe en trois listes l'ensemble des préfixes utilisés.
|
||||
*
|
||||
* Ces listes sont en cours d'élaboration.
|
||||
* Elles ne sont ni limitatives ni exhaustives ni ordonnées.
|
||||
* TODO
|
||||
*
|
||||
* - - -
|
||||
*
|
||||
* Le premier préfixe est l'adresse du fichier dans la hiérarchie "src":
|
||||
* ex: graphics_draw_
|
||||
* fsm_measures_manager_
|
||||
* util_draw_gl_
|
||||
* widget_one_rule_algebra_assign_
|
||||
*
|
||||
* Le deuxième préfixe est choisi dans une liste de fonctions types:
|
||||
* get, set, reset, read, write, print, edit, concat, design,
|
||||
* init, create, add, remove, erase, restore, trigger, draw, push
|
||||
* setup, shutdown, update, list, sort, seek, select, fix, debug,
|
||||
* render, realize, unrealize, activate, exec, stop, signal,
|
||||
*
|
||||
* Le troisième préfixe est choisi dans une liste d'objets ou d'états
|
||||
* qui sont modifiés par les fonctions.
|
||||
* Ce préfixe peut être composé de deux, trois ou quatre items
|
||||
* appartenant à cette liste et d'une conjonction si besoin.
|
||||
* ex: axis_slider, stack_slot_size, user_tree_model_child,
|
||||
* grids_on_space_faces_lines, current_model_before_editing, etc.
|
||||
*
|
||||
* number, string, view, image, window, list, tree, stack,
|
||||
* file, buffer, callback, signal,
|
||||
* widget, button, slider, color, glarea, shader,
|
||||
* point, line, plan, space_unit, site, arrow, slot, vertex, ridge, axis
|
||||
* state, rules, data, results, stock,
|
||||
*
|
||||
*
|
||||
*
|
||||
* Le 2024-10-05, seules trois fonctions ne sont pas nommées selon ces règles:
|
||||
* > create_axis_slider, free_stack_slot, free_stack_slot_size <
|
||||
*
|
||||
* et les noms de cinq autres pourraient être améliorés.
|
||||
* graphics_shutdown_graphics_stack > graphics_shutdown_stack < ex.
|
||||
* * * * * * * * * * * * * * * * * * * * * * * * * * */
|
||||
|
||||
|
||||
|
||||
create_axis_slider util/draw/gl 223 << to rename
|
||||
free_stack_slot graphics/init 36 << to rename
|
||||
free_stack_slot_size graphics/init 37 << to rename
|
||||
get_user_tree_model util/tree 66 static
|
||||
get_user_tree_model_child util/tree 49 static
|
||||
graphics_create_shader 187 ?
|
||||
graphics_debug_callback graphics/init 53 static
|
||||
graphics_draw graphics/draw 150
|
||||
graphics_draw_color graphics/draw 74
|
||||
graphics_draw_grids_on_space_faces_lines graphics/grid 129
|
||||
graphics_draw_grids_on_space_faces_vertex graphics/grid 75
|
||||
graphics_draw_line graphics/draw 100
|
||||
graphics_draw_one_arrow_line 365 ?
|
||||
graphics_draw_one_arrow_vertex 355 ?
|
||||
graphics_draw_plan graphics/draw 124
|
||||
graphics_draw_space_ridges_lines graphics/grid 62
|
||||
graphics_draw_space_ridges_vertex graphics/grid 30
|
||||
graphics_draw_vertex graphics/draw 40
|
||||
graphics_init graphics/init 108
|
||||
graphics_init_buffers graphics/init 326
|
||||
graphics_init_graphics_stack 127 ?
|
||||
graphics_init_shaders graphics/init 370
|
||||
graphics_model_setup graphics/init 228
|
||||
graphics_print_stack 221 ?
|
||||
graphics_render_stack 87 ?
|
||||
graphics_set_arrow 401 ?
|
||||
graphics_setup_glarea 89 ?
|
||||
graphics_shutdown graphics/init 169
|
||||
graphics_shutdown_graphics_stack 128 << to rename
|
||||
graphics_stack graphics/init 34
|
||||
graphics_stack_size graphics/init 35
|
||||
graphics_stack_t graphics.h
|
||||
graphics_update_axis_stack 129 ?
|
||||
fsm_add_data fsm/measures/data_list
|
||||
fsm_add_displayable fsm/preferences/manager
|
||||
fsm_add_measure fsm/measures/manager
|
||||
fsm_add_result fsm/results/manager
|
||||
fsm_disp_add_chart fsm/measures/disp_list
|
||||
fsm_disp_get_chart fsm/measures/disp_list
|
||||
fsm_disp_remove_chart fsm/measures/disp_list
|
||||
fsm_enum_exec_edit fsm.h
|
||||
fsm_enum_journal_severity fsm.h
|
||||
fsm_enum_journal_source fsm.h
|
||||
fsm_enum_measure_type fsm.h
|
||||
fsm_enum_state_rules_data fsm.h
|
||||
fsm_enum_store_restore_reset fsm.h
|
||||
fsm_get_data fsm/measures/data_list
|
||||
fsm_get_exec_edit fsm/dispatch
|
||||
fsm_get_preferences_state fsm/dispatch
|
||||
fsm_get_state_rules_data fsm/dispatch
|
||||
fsm_init fsm/dispatch
|
||||
fsm_journal_clear src/journal
|
||||
fsm_journal_event fsm/dispatch
|
||||
fsm_journal_init src/journal
|
||||
fsm_journal_length src/journal
|
||||
fsm_journal_pop_back src/journal
|
||||
fsm_journal_publication_request fsm/dispatch
|
||||
fsm_journal_publish src/journal
|
||||
fsm_journal_push_front src/journal
|
||||
fsm_journal_seek src/journal
|
||||
fsm_list_init_displayables fsm/prefer
|
||||
fsm_list_init_measures fsm/measures/manager
|
||||
fsm_list_init_preferences fsm/preferences/manager
|
||||
fsm_list_init_results fsm/results/manager
|
||||
fsm_list_tools_clear fsm/measures/tools_list
|
||||
fsm_list_tools_insert fsm/measures/tools_list
|
||||
fsm_list_tools_length fsm/measures/tools_list
|
||||
fsm_list_tools_pop fsm/measures/tools_list
|
||||
fsm_list_tools_test fsm/measures/tools_list
|
||||
fsm_list_tools_view fsm/measures/tools_list
|
||||
fsm_remove_data fsm/measures/data_list
|
||||
fsm_reset_all_situations_values fsm/preferences/manager
|
||||
fsm_rule_trig_measure fsm/measures/manager
|
||||
fsm_set_exec_edit fsm/dispatch
|
||||
fsm_set_preferences_modified fsm/dispatch
|
||||
fsm_set_state_rules_data fsm/dispatch
|
||||
fsm_set_store_restore_reset fsm/dispatch
|
||||
fsm_struct_journal fsm.h
|
||||
fsm_struct_journal_unit fsm.h
|
||||
fsm_struct_list_data fsm.h
|
||||
fsm_struct_list_disp fsm.h
|
||||
fsm_struct_list_tool fsm.h
|
||||
on_auto_notification signal 37 static
|
||||
on_axis_value_change signal 181
|
||||
on_bind_user_tree_factory signal 81
|
||||
on_clicked_topbar_right_home signal 373 << to rename
|
||||
on_clicked_topbar_right_search signal 364 << to rename
|
||||
on_discard_current_model_before_editing signal 228
|
||||
on_entry_name_delete_after signal 547
|
||||
on_entry_name_insert_after signal 542
|
||||
on_glarea_realize signal 132
|
||||
on_glarea_render signal 112
|
||||
on_glarea_unrealize signal 158
|
||||
on_measure_ ... signal 453 sqq.
|
||||
on_realize_debug util/draw/gl 335 static
|
||||
on_render_debug util/draw/gl 345 static
|
||||
on_resetting_XYZ_in_state_page signal 404
|
||||
on_save_current_model_before_editing signal 220
|
||||
on_select_rules_first signal 446
|
||||
on_setup_user_tree_factory signal 73
|
||||
on_situations_box_do_reset signal 412
|
||||
on_start_new_measure signal 439
|
||||
on_toggle_exec_edit signal 254 << to rename
|
||||
on_toggle_state_rules_data signal 286 << to rename
|
||||
on_topbar_right_measure_clicked signal 426
|
||||
on_updating_objects_transparencies signal 389
|
||||
on_user_tree_expander_toggled signal 64 static
|
||||
on_windows_activation widget/dispatch 67
|
||||
on_windows_startup widget/dispatch 61
|
||||
on_write_current_model signal 236
|
||||
parse_model_get_dim util/parse 231
|
||||
parse_model_get_dim_value util/parse 244
|
||||
parse_model_get_multiplicity util/parse 255
|
||||
parse_model_get_next_arrow util/parse 346
|
||||
parse_model_get_next_state util/parse 269
|
||||
parse_model_get_state_arrows_count util/parse 295
|
||||
parse_model_init 29 (not used)
|
||||
parse_model_shutdown util/parse 88
|
||||
parse_parse_model_init util/parse 46
|
||||
shader frag graphics/shader
|
||||
shader vert graphics/shader
|
||||
stack_index stack_index 38
|
||||
stack_index_size stack_index 39
|
||||
stack_index_t util/draw/gl.c 32
|
||||
switch_state_rules_data signal 305 static
|
||||
TreeNode_t widget.h (rename ?)
|
||||
util_concat util/strings_op
|
||||
util_gl_clean_stack_index util/draw/gl.c 150
|
||||
util_gl_get_stack util/draw/gl.c 66
|
||||
util_gl_init_stack util/draw/gl.c 102
|
||||
util_gl_is_ready util/draw/gl.c 84
|
||||
util_gl_is_util_ready 92 TODO
|
||||
util_gl_render_stack util/draw/gl.c 166
|
||||
util_gl_set_arrow util/draw/gl.c 42
|
||||
util_gl_setup_glarea util/draw/gl.c 364
|
||||
util_gl_shutdown_all_stacks util/draw/gl.c 207
|
||||
util_gl_shutdown_stack util/draw/gl.c 133
|
||||
util_gl_update_axis util/draw/gl.c 187
|
||||
util_list_2x2_ ^c^v (8 fonctions) util/list_2x2
|
||||
util_pile_ ^c^v (5 fonctions) util/pile
|
||||
util_read_file util/io
|
||||
util_sorted_list_ ^c^v (5 fonctions) util/sorted_list
|
||||
util_test_double_list util/tests
|
||||
util_test_pile util/tests
|
||||
util_test_sorted_list util/tests
|
||||
util_trigger_test util/tests
|
||||
widget_add_tree_child_node util/tree 32
|
||||
widget_create_user_rules_tree_node util/tree 41
|
||||
widget_design_dialog_window widget/dispatch
|
||||
widget_design_main_window widget/dispatch
|
||||
widget_design_text_window widget/dispatch
|
||||
widget_measure_do_select_rules_first widget/measure/dispatch
|
||||
widget_measure_do_ ... 295 sqq.
|
||||
widget_measure_event_occurences_dates widget/measure/dispatch
|
||||
widget_measure_event_occurences_nb widget/measure/dispatch
|
||||
widget_measure_event_occurences_situations widget/measure/dispatch
|
||||
widget_measure_other_events_between_the_two widget/measure/dispatch
|
||||
widget_measure_time_elapsed_between_two_events widget/measure/dispatch
|
||||
widget_get_address_text_theory widget/topbar/dispatch
|
||||
widget_get_address_text_practice widget/topbar/dispatch
|
||||
widget_get_btt_label_data widget/topbar/left
|
||||
widget_get_btt_label_rules widget/topbar/left
|
||||
widget_get_btt_label_state widget/topbar/left
|
||||
widget_get_btt_label_synth widget/topbar/left
|
||||
widget_get_dialog_window widget/dispatch
|
||||
widget_get_graph_view_control widget/state/middle
|
||||
widget_get_main_window widget/dispatch
|
||||
widget_get_non_time_dependent widget/synth/dispatch
|
||||
widget_get_object_transparency widget/state/top
|
||||
widget_get_page_data widget/results/dispatch
|
||||
widget_get_page_engine 104 TODO
|
||||
widget_get_page_measure widget/measure/dispatch
|
||||
widget_get_page_state widget/state/dispatch
|
||||
widget_get_page_synth widget/synth/dispatch
|
||||
widget_get_pane_all_rules_left widget/all_rules/dispatch
|
||||
widget_get_pane_selected_rule_right widget/one_rule/dispatch
|
||||
widget_get_results_box_display widget/results/display
|
||||
widget_get_results_box_organize widget/results/organize
|
||||
widget_get_results_box_time widget/results/display
|
||||
widget_get_rule_edition_tools widget/one_rule/geometry/edit
|
||||
widget_get_rule_investigation_tools widget/one_rule/geometry/investigate
|
||||
widget_get_rule_geometry_and_algebra 187 TODO (not yet used)
|
||||
widget_get_rules_pilot_box widget/all_rules/tree/pilot_box
|
||||
widget_get_rules_tree_tools widget/all_rules/tree/pilot_box
|
||||
widget_get_rules_use widget/all_rules/tree/freq
|
||||
widget_get_selected_rule widget/one_rule/dispatch
|
||||
widget_get_selected_rule_algebra widget/one_rule/algebra/dispatch
|
||||
widget_get_selected_rule_assignations_list_btt widget/one_rule/algebra/assign
|
||||
widget_get_selected_rule_before_after widget/one_rule/geometry/geometry
|
||||
widget_get_selected_rule_camera widget/one_rule/geometry/camera
|
||||
widget_get_selected_rule_conditions_list_btt widget/one_rule/algebra/conditions
|
||||
widget_get_selected_rule_geometry widget/one_rule/geometry/dispatch
|
||||
widget_get_selected_rule_identity_btt widget/one_rule/algebra/identity
|
||||
widget_get_sequence_control widget/state/bottom
|
||||
widget_get_space_edit_control widget/state/bottom
|
||||
widget_get_space_view widget/state/middle
|
||||
widget_get_space_vs_non_time_dependent widget/synth/dispatch
|
||||
widget_get_text_from_address widget/topbar/modal
|
||||
widget_get_text_window widget/dispatch
|
||||
widget_get_time_dependent widget/synth/time
|
||||
widget_get_user_rules_tree util/tree 88
|
||||
widget_reset_XYZ_in_state_pane widget/state/middle TODO (dispatch)
|
||||
widget_reset_XYZ_scrollbars_rule 166 TODO
|
||||
widget_reset_XYZ_scrollbars_state 167 TODO
|
||||
widget_reset_XYZ_scrollbars_synth 168 TODO
|
||||
widget_set_item_text widget/one_rule/algebra/dispatch
|
||||
widget_set_objects_value widget/state/top
|
||||
widget_set_situations_value widget/state/top
|
||||
window_design_topbar_left widget/dispatch
|
||||
window_design_topbar_right widget/dispatch
|
||||
|
||||
Loading…
Reference in New Issue