Written a proper documentation for the Python gui.core module.

5 files changed, 80 insertions, 98 deletions

diff --git a/plugins/pychrysalide/core/module.c b/plugins/pychrysalide/core/module.c
index 27113a0..11cd8ed 100644
--- a/plugins/pychrysalide/core/module.c
+++ b/plugins/pychrysalide/core/module.c
@@ -59,7 +59,7 @@ bool add_core_module(PyObject *super)
     "This module provides access to the Chrysalide core properties through" \
     " the Python bindings.\n"                                               \
     "\n"                                                                    \
-    "Most of these features are singleton objects.\n"                       \
+    "Some of these features are singleton objects.\n"                       \
     "\n"                                                                    \
     "As attributes are not allowed for Python modules, all these"           \
     " property accesses are handled with methods."
diff --git a/plugins/pychrysalide/gui/core/items.c b/plugins/pychrysalide/gui/core/items.c
index bc5bbd6..f60cd93 100644
--- a/plugins/pychrysalide/gui/core/items.c
+++ b/plugins/pychrysalide/gui/core/items.c
@@ -71,6 +71,16 @@ static PyObject *py_items_change_current_content(PyObject *self, PyObject *args)
     GLoadedContent *content;                /* Instance GLib correspondante*/
     int ret;                                /* Bilan de lecture des args.  */
 
+#define ITEMS_CHANGE_CURRENT_CONTENT_METHOD PYTHON_METHOD_DEF           \
+(                                                                       \
+    change_current_content, "content",                                  \
+    METH_VARARGS, py_items,                                             \
+    "Change the current loaded content in the GUI."                     \
+    "\n"                                                                \
+    "The new content has to be a pychrysalide.analysis.LoadedContent"   \
+    " instance."                                                        \
+)
+
     ret = PyArg_ParseTuple(args, "O&", convert_to_loaded_content, &content);
     if (!ret) return NULL;
 
@@ -99,6 +109,16 @@ static PyObject *py_items_change_current_view(PyObject *self, PyObject *args)
     GLoadedPanel *panel;                    /* Instance GLib correspondante*/
     int ret;                                /* Bilan de lecture des args.  */
 
+#define ITEMS_CHANGE_CURRENT_VIEW_METHOD PYTHON_METHOD_DEF              \
+(                                                                       \
+    change_current_view, "view",                                        \
+    METH_VARARGS, py_items,                                             \
+    "Change the current view in the GUI."                               \
+    "\n"                                                                \
+    "The new content has to be a pychrysalide.glibext.LoadedPanel"      \
+    " instance."                                                        \
+)
+
     ret = PyArg_ParseTuple(args, "O&", convert_to_loaded_panel, &panel);
     if (!ret) return NULL;
 
@@ -127,6 +147,16 @@ static PyObject *py_items_update_current_view(PyObject *self, PyObject *args)
     GLoadedPanel *panel;                    /* Instance GLib correspondante*/
     int ret;                                /* Bilan de lecture des args.  */
 
+#define ITEMS_UPDATE_CURRENT_VIEW_METHOD PYTHON_METHOD_DEF          \
+(                                                                   \
+    update_current_view, "view",                                    \
+    METH_VARARGS, py_items,                                         \
+    "Update the current view in the GUI."                           \
+    "\n"                                                            \
+    "The new view has to be a pychrysalide.glibext.LoadedPanel"     \
+    " instance."                                                    \
+)
+
     ret = PyArg_ParseTuple(args, "O&", convert_to_loaded_panel, &panel);
     if (!ret) return NULL;
 
@@ -137,8 +167,6 @@ static PyObject *py_items_update_current_view(PyObject *self, PyObject *args)
 }
 
 
-
-
 /******************************************************************************
 *                                                                             *
 *  Paramètres  : self = classe représentant un binaire.                       *
@@ -157,6 +185,16 @@ static PyObject *py_items_update_project(PyObject *self, PyObject *args)
     GStudyProject *project;                 /* Instance GLib correspondante*/
     int ret;                                /* Bilan de lecture des args.  */
 
+#define ITEMS_UPDATE_PROJECT_METHOD PYTHON_METHOD_DEF               \
+(                                                                   \
+    update_project, "project",                                      \
+    METH_VARARGS, py_items,                                         \
+    "Update the GUI for the current project."                       \
+    "\n"                                                            \
+    "The provided project has to be an instance (or a subclass)"    \
+    " of pychrysalide.analysis.StudyProject."                       \
+)
+
     ret = PyArg_ParseTuple(args, "O&", convert_to_study_project, &project);
     if (!ret) return NULL;
 
@@ -171,70 +209,7 @@ static PyObject *py_items_update_project(PyObject *self, PyObject *args)
 *                                                                             *
 *  Paramètres  : -                                                            *
 *                                                                             *
-*  Description : Fournit un accès à une définition de type à diffuser.        *
-*                                                                             *
-*  Retour      : Définition d'objet pour Python.                              *
-*                                                                             *
-*  Remarques   : -                                                            *
-*                                                                             *
-******************************************************************************/
-
-PyTypeObject *get_python_items_type(void)
-{
-    static PyMethodDef py_items_methods[] = {
-        {
-            "change_current_content", py_items_change_current_content,
-            METH_VARARGS | METH_STATIC,
-            "change_current_content($self, content/)\n--\n\nChange the current loaded content in the GUI."
-        },
-        {
-            "change_current_view", py_items_change_current_view,
-            METH_VARARGS | METH_STATIC,
-            "change_current_view($self, view/)\n--\n\nChange the current view in the GUI."
-        },
-        {
-            "update_current_view", py_items_update_current_view,
-            METH_VARARGS | METH_STATIC,
-            "update_current_view($self, view/)\n--\n\nUpdate the current view in the GUI."
-        },
-        {
-            "update_project", py_items_update_project,
-            METH_VARARGS | METH_STATIC,
-            "update_project($self, view/)\n--\n\nUpdate the GUI for the current project."
-        },
-        { NULL }
-    };
-
-    static PyGetSetDef py_items_getseters[] = {
-        { NULL }
-    };
-
-    static PyTypeObject py_items_type = {
-
-        PyVarObject_HEAD_INIT(NULL, 0)
-
-        .tp_name = "pychrysalide.gui.core.items",
-        .tp_basicsize = sizeof(PyObject),
-
-        .tp_flags = Py_TPFLAGS_DEFAULT,
-
-        .tp_doc = "Dealing with items of the GUI.",
-
-        .tp_methods = py_items_methods,
-        .tp_getset  = py_items_getseters
-
-    };
-
-    return &py_items_type;
-
-}
-
-
-/******************************************************************************
-*                                                                             *
-*  Paramètres  : module = module dont la définition est à compléter.          *
-*                                                                             *
-*  Description : Prend en charge l'objet 'pychrysalide.gui.core.items'.       *
+*  Description : Définit une extension du module 'gui.core' à compléter.      *
 *                                                                             *
 *  Retour      : Bilan de l'opération.                                        *
 *                                                                             *
@@ -242,27 +217,23 @@ PyTypeObject *get_python_items_type(void)
 *                                                                             *
 ******************************************************************************/
 
-bool ensure_python_items_is_registered(void)
+bool populate_gui_core_module_with_items(void)
 {
-    PyTypeObject *type;                     /* Type Python de 'items'      */
+    bool result;                            /* Bilan à retourner           */
     PyObject *module;                       /* Module à recompléter        */
 
-    type = get_python_items_type();
-
-    if (!PyType_HasFeature(type, Py_TPFLAGS_READY))
-    {
-        type->tp_new = PyType_GenericNew;
-
-        if (PyType_Ready(type) != 0)
-            return false;
-
-        module = get_access_to_python_module("pychrysalide.gui.core");
+    static PyMethodDef py_items_methods[] = {
+        ITEMS_CHANGE_CURRENT_CONTENT_METHOD,
+        ITEMS_CHANGE_CURRENT_VIEW_METHOD,
+        ITEMS_UPDATE_CURRENT_VIEW_METHOD,
+        ITEMS_UPDATE_PROJECT_METHOD,
+        { NULL }
+    };
 
-        if (!register_python_module_object(module, type))
-            return false;
+    module = get_access_to_python_module("pychrysalide.gui.core");
 
-    }
+    result = register_python_module_methods(module, py_items_methods);
 
-    return true;
+    return result;
 
 }
diff --git a/plugins/pychrysalide/gui/core/items.h b/plugins/pychrysalide/gui/core/items.h
index 1e73263..0ad602e 100644
--- a/plugins/pychrysalide/gui/core/items.h
+++ b/plugins/pychrysalide/gui/core/items.h
@@ -31,11 +31,8 @@
 
 
 
-/* Fournit un accès à une définition de type à diffuser. */
-PyTypeObject *get_python_items_type(void);
-
-/* Prend en charge l'objet 'pychrysalide.gui.core.items'. */
-bool ensure_python_items_is_registered(void);
+/* Définit une extension du module 'gui.core' à compléter. */
+bool populate_gui_core_module_with_items(void);
 
 
 
diff --git a/plugins/pychrysalide/gui/core/module.c b/plugins/pychrysalide/gui/core/module.c
index 47c35b1..23a769d 100644
--- a/plugins/pychrysalide/gui/core/module.c
+++ b/plugins/pychrysalide/gui/core/module.c
@@ -52,12 +52,21 @@ bool add_gui_core_module(PyObject *super)
     bool result;                            /* Bilan à retourner           */
     PyObject *module;                       /* Sous-module mis en place    */
 
+#define PYCHRYSALIDE_CORE_DOC                                               \
+    "This module provides access to the Chrysalide GUI core properties"     \
+    " through the Python bindings.\n"                                       \
+    "\n"                                                                    \
+    "Some of these features are singleton objects.\n"                       \
+    "\n"                                                                    \
+    "As attributes are not allowed for Python modules, all these"           \
+    " property accesses are handled with methods."
+
     static PyModuleDef py_chrysalide_gui_core_module = {
 
         .m_base = PyModuleDef_HEAD_INIT,
 
         .m_name = "pychrysalide.gui.core",
-        .m_doc = "Python module for Chrysalide.gui.core",
+        .m_doc = PYCHRYSALIDE_CORE_DOC,
 
         .m_size = -1,
 
@@ -90,8 +99,8 @@ bool populate_gui_core_module(void)
 
     result = true;
 
-    if (result) result = ensure_python_items_is_registered();
     if (result) result = populate_gui_core_module_with_global();
+    if (result) result = populate_gui_core_module_with_items();
     if (result) result = populate_gui_core_module_with_panels();
 
     assert(result);
diff --git a/plugins/pychrysalide/gui/core/panels.c b/plugins/pychrysalide/gui/core/panels.c
index 3a3001c..a0bf853 100644
--- a/plugins/pychrysalide/gui/core/panels.c
+++ b/plugins/pychrysalide/gui/core/panels.c
@@ -39,7 +39,7 @@
 
 
 /* Enregistre un panneau comme partie intégrante de l'éditeur. */
-static PyObject *py_panels_register_item(PyObject *, PyObject *);
+static PyObject *py_panels_register_panel(PyObject *, PyObject *);
 
 
 
@@ -56,12 +56,22 @@ static PyObject *py_panels_register_item(PyObject *, PyObject *);
 *                                                                             *
 ******************************************************************************/
 
-static PyObject *py_panels_register_item(PyObject *self, PyObject *args)
+static PyObject *py_panels_register_panel(PyObject *self, PyObject *args)
 {
     GPanelItem *item;                       /* Panneau à traiter           */
     GGenConfig *config;                     /* Configuration à consulter   */
     int ret;                                /* Bilan de lecture des args.  */
 
+#define PANELS_REGISTER_PANEL_METHOD PYTHON_METHOD_DEF              \
+(                                                                   \
+    register_panel, "panel",                                        \
+    METH_VARARGS, py_panels,                                        \
+    "Register a panel for the GUI."                                 \
+    "\n"                                                            \
+    "The provided panel has to be a pychrysalide.gui.PanelItem"     \
+    " instance."                                                    \
+)
+
     config = NULL;
 
     ret = PyArg_ParseTuple(args, "O&", convert_to_panel_item, &item);
@@ -104,13 +114,8 @@ bool populate_gui_core_module_with_panels(void)
     PyObject *module;                       /* Module à recompléter        */
 
     static PyMethodDef py_panels_methods[] = {
-
-        { "register_panel", py_panels_register_item,
-          METH_VARARGS,
-          "register_panel(item, config, /)\n--\n\nRegister a panel for the GUI."
-        },
+        PANELS_REGISTER_PANEL_METHOD,
         { NULL }
-
     };
 
     module = get_access_to_python_module("pychrysalide.gui.core");