WIP: commentaires (en Français seulement) 2ème version

include/base.h

@@ -37,6 +37,10 @@
 #include <glib-2.0/glib.h>
 #define G_APPLICATION_DEFAULT_FLAGS 0
 
+/*
+ * Ici, des données transversales, communes à plusieurs parties de l'application
+ * et de la description de la fenêtre.
+ */
 enum
 {
     X_AXIS,

src/main.c

@@ -28,7 +28,33 @@
 #include "../include/base.h"
 #include "../include/ui.h"
 
-/* -------------------------------------------------------------------------- */
+/*
+ * Comment gem_graph_client crée-t-il son application et sa fenêtre ?
+ *
+ * gem_graph_client_application_new() est une fonction primitive de gtk.h
+ * qui permet de (sert à) donner au gestionnaire de bureau, Gnome, les informations
+ * nécessaires et suffisantes pour initialiser une nouvelle application.
+ *
+ * gem_graph_client réécrit cette fonction à la fin de application.c
+ * en l'utilisant pour passer à Gnome les informations suivantes :
+ * - le nom de l'application (son identité) et
+ * - des flags (initialisés à des valeurs par défaut)
+ *
+ * Une fois l'espace mémoire nécessaire réservé et un nouveau thread créé et
+ * prêt à être exécuté, la nouvelle application peut 'démarrer'.
+ * C'est une autre primitive de gtk.h : g_application_run()
+ * qui donne à Gnome l'ordre de lancer ce thread et ainsi de commencer à
+ * exécuter l'application "gem_graph_client".
+ *
+ * Une fois l'application lancée, main() n'a plus rien à faire.
+ * La suite est décrite dans
+ * - application.c (activation / désactivation des actions, ajouts d'accélérateurs)
+ * - gemgraph.ui (description statique de la fenêtre)
+ * - window.c (description dynamique de la fenêtre)
+ * - events.c (description des actions)
+ * - tree.c (description d'une structure particulière) (sera répartie ultérieurement ?)
+ * - base.h (définitions 'transversales'/(communes) utilisables par plusieurs ressources
+ */
 
 int main(int argc, char **argv)
 {
@@ -41,50 +67,3 @@ int main(int argc, char **argv)
     res = g_application_run(G_APPLICATION(app), argc, argv);
     return res;
 }
-
-/*
- * Comment gem_graph_client crée-t-il son application et sa fenêtre ?
- *
- * gem_graph_client_application_new() est une fonction primitive de gtk.h
- * qui permet de donner au gestionnaire de bureau, Gnome, les informations
- * nécessaires et suffisantes pour initialiser une nouvelle application.
- *
- * Ces informations sont :
- * - le nom de l'application (son identité) et
- * - des flags  initialiséà leurs valeurs par défaut
- *
- * gem_graph_client_application_new() est réécrite à la fin de application.c
- *
- * Une fois l'espace mémoire nécessaire réservé,
- * la nouvelle application peut démarrer
- * et c'est une autre primitive de gtk.h : g_application_run()
- * qui donne à Gnome l'ordre de lancer le thread
- * qui exécutera cette application.
- *
- * Une fois l'application lancée, main() n'a plus rien à faire.
- * La suite va se dérouler d'abord dans application.c puis dans window.c
- */
-
-/*
- * How does gem_graph_client create its application and window?
- *
- * gem_graph_client_application_new() is a primitive function of gtk.h
- * which provides the desktop manager, Gnome, with the information
- * necessary and sufficient information to initialize a new application.
- *
- * This information is :
- * - the application name (its identity) and
- * - some flags set to their default values
- *
- * gem_graph_client_application_new() is rewritten at the end of application.c
- *
- * Once the necessary memory space has been reserved,
- * the new application can start
- * and this is another gtk.h primitive: g_application_run()
- * which instructs Gnome to launch the thread
- * which will run this application.
- *
- * Once the application has been launched, main() has nothing more to do.
- * The rest will take place first in application.c and then in window.c.
- */
-

src/ui/application.c

@@ -25,6 +25,37 @@
 #include "../../include/base.h"
 #include "../../include/ui.h"
 
+/* https://docs.gtk.org/gtk4/input-handling.html */
+/*
+ * [application.c] donne au gestionnaire de bureau Gnome toutes les informations
+ * nécessaires au fonctionnement de l'application gem_graph_client.
+ *
+ * Lorsque Gnome reçoit de gtk la commande : g_application_run()
+ * il répond en exécutant deux fonctions primitives
+ * qui doivent se trouver - être réécrites - dans application.c :
+ * - gem_graph_client_application_class_init() et
+ * - gem_graph_client_application_init()
+ *
+ * gem_graph_client_application_class_init()
+ * crée la classe application qui décrira l'application gem_graph_client
+ * et la rend active.
+ *
+ * gem_graph_client_application_init()
+ * spécifie les propriétés initiales de l'application de manière détaillée.
+ * L'une de ses premières tâches et de désactiver des actions
+ * qui pourraient être demandées par l'utilisateur
+ * alors que l'application n'est pas encore prête à y répondre.
+ *
+ * Lorsque la totalité de l'application sera fonctionnelle,
+ * la fenêtre sera créée et les actions préalablement désactivées
+ * seront réactivées par : gem_graph_client_application_activate()
+ *
+ * La description détaillée de la fenêtre se trouve dans
+ * - gemgraph.ui (description statique des widgets et noms des "events" associés)
+ * - window.c (description dynamique des widgets)
+ * - events.c (description des évènements)
+ */
+
 struct _GemGraphClientApplication
 {
     GtkApplication parent_instance;
@@ -149,63 +180,3 @@ GemGraphClientApplication *gem_graph_client_application_new(
                        NULL);
 }
 
-/* https://docs.gtk.org/gtk4/input-handling.html */
-
-
-/*
- * Le rôle de application.c est de donner au gestionnaire de bureau Gnome
- * toutes les informations nécessaires
- * au fonctionnement de l'application gem_graph_client.
- *
- * Lorsque Gnome reçoit de gtk la commande : g_application_run()
- * il répond en exécutant deux fonctions primitives
- * qui doivent se trouver dans application.c :
- * - gem_graph_client_application_class_init() et
- * - gem_graph_client_application_init()
- *
- * gem_graph_client_application_class_init()
- * crée la classe application qui décrira l'application gem_graph_client
- * et la rend active.
- *
- * gem_graph_client_application_init()
- * spécifie les propriétés de l'application de manière plus détaillée.
- * L'une de ses premières tâches et de désactiver des actions
- * qui pourraient être demandées par l'utilisateur
- * alors que l'application n'est pas encore prête à y répondre.
- *
- * Lorsque la totalité de l'application aura été mise en place
- * et qu'elle sera fonctionnelle,
- * la fenêtre sera créée et ces actions seront réactivées par :
- * gem_graph_client_application_activate()
- *
- * La description de la fenêtre se trouvent dans
- * - window.c (description dynamique des widgets)
- * - events.c
- */
-
-/*
- * The role of application.c is to give the Gnome desktop manager
- * all the necessary information to run the application gem_graph_client.
- *
- * When Gnome receives the g_application_run() command from gtk
- * it responds by executing two primitive functions
- * described in the application.c file:
- * - gem_graph_client_application_class_init() and
- * - gem_graph_client_application_init()
- *
- * gem_graph_client_application_class_init()
- * creates the application class that describes the gem_graph_client
- * application and makes it active.
- *
- * gem_graph_client_application_init()
- * specifies the application's properties in greater detail.
- * One of its first tasks is to disable actions which may be requested by the user
- * when the application is not yet ready to respond.
- *
- * Once the entire application is up and functional,
- * the window will be created and these actions will be reactivated by :
- * gem_graph_client_application_activate()
- *
- * Once the application is up and running, the window can be created.
- * Window operations are described in window.c
- */

src/ui/events.c

@@ -28,7 +28,9 @@
 #include "../../include/graphics.h"
 #include "../../include/ui.h"
 
-
+/*
+ * Ici, seuls les événements élémentaires sont admis !
+ */
 
 void on_about_action(GSimpleAction *action,
                      GVariant *parameter,

src/ui/tree.c

@@ -30,6 +30,13 @@
 
 #include <gtk/gtk.h>
 
+/*
+ * Ici règne le désordre le plus complet !
+ * Attention vous entrez à vos risques et périls dans un laboratoire de recherche.
+ * Rien n'est balisé. Tout peut arriver. Le code est encombré de déchets inutiles.
+ * Les commentaires sont inadaptés, incompréhensibles ou inutilisables
+ */
+
 enum
 {
   COL_FIRST_NAME = 0,

src/ui/window.c

@@ -29,7 +29,18 @@
 #include "../../include/base.h"
 #include "../../include/ui.h"
 
-/* -------------------------------------------------------------------------- */
+/* https://docs.gtk.org/gtk4/getting_started.html */
+/*
+ * window.c décrit tout ce qui concerne les différents widgets disposés dans la fenêtre
+ * et qui ne peut être décrit dans le fichier XML (statique) gemgraph.ui
+ *
+ * Il peut s'agir de modifications concernant :
+ * - leur positionnement relatif
+ * - leur apparence
+ * - leur connexion conditionnelle à certains événements
+ *
+ * Les événements élémentaires eux-même sont décrits dans le fichier events.c
+ */
 
 float rotation_angles[N_AXIS] = { 0.0 }; // Rotation angles on each axis
 
@@ -222,6 +233,10 @@ void ui_setup_glarea(GtkGLArea *target, GtkBox *target_controls)
     gtk_gl_area_get_required_version( GTK_GL_AREA(gl_area), &minor, &major);
 }
 
+/*
+ * Est-ce que cette fonction n'aurait pas sa place dans events.c ?
+ * Mmumm ? Pas assez élémentaire mon cher Watson ! Notez le if else !
+ */
 void ui_toggle_sidebar(void)
 {
     int position = gtk_paned_get_position(window->main_paned);
@@ -270,7 +285,3 @@ GtkWidget *create_tree_button(void)
 
     return button;
 }
-
-/* https://docs.gtk.org/gtk4/getting_started.html */
-
-