Refreshed the Python documentation for the core features.

6 files changed, 116 insertions, 57 deletions

diff --git a/plugins/pychrysalide/core/demanglers.c b/plugins/pychrysalide/core/demanglers.c
index 216b7e1..a967491 100644
--- a/plugins/pychrysalide/core/demanglers.c
+++ b/plugins/pychrysalide/core/demanglers.c
@@ -37,7 +37,7 @@
 
 
 /* Fournit le décodeur de désignations correspondant à un type. */
-static PyObject *py_demanglers_get_for_type(PyObject *, PyObject *);
+static PyObject *py_demanglers_get_demangler_for_key(PyObject *, PyObject *);
 
 
 
@@ -54,17 +54,27 @@ static PyObject *py_demanglers_get_for_type(PyObject *, PyObject *);
 *                                                                             *
 ******************************************************************************/
 
-static PyObject *py_demanglers_get_for_type(PyObject *self, PyObject *args)
+static PyObject *py_demanglers_get_demangler_for_key(PyObject *self, PyObject *args)
 {
     PyObject *result;                       /* Désignation à retourner     */
     const char *key;                        /* Nom court du format         */
     int ret;                                /* Bilan de lecture des args.  */
     GCompDemangler *demangler;              /* Décodeur mis en place       */
 
+#define DEMANGLERS_GET_DEMANGLER_FOR_KEY_METHOD PYTHON_METHOD_DEF           \
+(                                                                           \
+    get_demangler_for_key, "key, /",                                        \
+    METH_VARARGS, py_demanglers,                                            \
+    "Create a new demangler for a given type of encoding, provided as"      \
+    " a key string.\n"                                                      \
+    "\n"                                                                    \
+    "The return instance is a pychrysalide.mangling.CompDemangler subclass."\
+)
+
     ret = PyArg_ParseTuple(args, "s", &key);
     if (!ret) return NULL;
 
-    demangler = get_compiler_demangler_for_type(key);
+    demangler = get_compiler_demangler_for_key(key);
 
     if (demangler != NULL)
     {
@@ -103,13 +113,8 @@ bool populate_core_module_with_demanglers(void)
     PyObject *module;                       /* Module à recompléter        */
 
     static PyMethodDef py_demanglers_methods[] = {
-
-        { "get_for_type", py_demanglers_get_for_type,
-          METH_VARARGS,
-          "get_for_type(key, /)\n--\n\nCreate a new demangler for a given type of encoding."
-        },
+        DEMANGLERS_GET_DEMANGLER_FOR_KEY_METHOD,
         { NULL }
-
     };
 
     module = get_access_to_python_module("pychrysalide.core");
diff --git a/plugins/pychrysalide/core/global.c b/plugins/pychrysalide/core/global.c
index 86133d2..ff892a8 100644
--- a/plugins/pychrysalide/core/global.c
+++ b/plugins/pychrysalide/core/global.c
@@ -107,6 +107,16 @@ static PyObject *py_global_get_content_explorer(PyObject *self, PyObject *args)
     PyObject *result;                       /* Instance Python à retourner */
     GContentExplorer *explorer;             /* Gestionnaire natif récupéré */
 
+#define GLOBAL_GET_CONTENT_EXPLORER_METHOD PYTHON_METHOD_DEF            \
+(                                                                       \
+    get_content_explorer, "",                                           \
+    METH_NOARGS, py_global,                                             \
+    "Get the global exploration manager discovering contents."          \
+    "\n"                                                                \
+    "The returned object is a pychrysalide.analysis.ContentExplorer"    \
+    " instance used as singleton."                                      \
+)
+
     explorer = get_current_content_explorer();
 
     if (explorer != NULL)
@@ -143,6 +153,17 @@ static PyObject *py_global_get_content_resolver(PyObject *self, PyObject *args)
     PyObject *result;                       /* Instance Python à retourner */
     GContentResolver *resolver;             /* Gestionnaire natif récupéré */
 
+#define GLOBAL_GET_CONTENT_RESOLVER_METHOD PYTHON_METHOD_DEF            \
+(                                                                       \
+    get_content_resolver, "",                                           \
+    METH_NOARGS, py_global,                                             \
+    "Get the global resolution manager translating binary contents"     \
+    " into loaded contents."                                            \
+    "\n"                                                                \
+    "The returned object is a pychrysalide.analysis.ContentResolver"    \
+    " instance used as singleton."                                      \
+)
+
     resolver = get_current_content_resolver();
 
     if (resolver != NULL)
@@ -179,6 +200,16 @@ static PyObject *py_global_get_current_project(PyObject *self, PyObject *args)
     PyObject *result;                       /* Instance Python à retourner */
     GStudyProject *project;                 /* Projet courant récupéré     */
 
+#define GLOBAL_GET_CURRENT_PROJECT_METHOD PYTHON_METHOD_DEF         \
+(                                                                   \
+    get_current_project, "",                                        \
+    METH_NOARGS, py_global,                                         \
+    "Get the current global project."                               \
+    "\n"                                                            \
+    "The returned object is an instance of type"                    \
+    " pychrysalide.analysis.StudyProject."                          \
+)
+
     project = get_current_project();
 
     if (project != NULL)
@@ -215,6 +246,16 @@ static PyObject *py_global_set_current_project(PyObject *self, PyObject *args)
     GStudyProject *project;                 /* Version GLib du projet      */
     int ret;                                /* Bilan de lecture des args.  */
 
+#define GLOBAL_SET_CURRENT_PROJECT_METHOD PYTHON_METHOD_DEF         \
+(                                                                   \
+    set_current_project, "project",                                 \
+    METH_VARARGS, py_global,                                        \
+    "Set the current global 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;
 
@@ -246,24 +287,11 @@ bool populate_core_module_with_global(void)
 
     static PyMethodDef py_global_methods[] = {
         GLOBAL_IS_BATCH_MODE_METHOD,
-        { "get_content_explorer", py_global_get_content_explorer,
-          METH_NOARGS,
-          "get_content_explorer(, /)\n--\n\nGet the global exploration manager discovering contents."
-        },
-        { "get_content_resolver", py_global_get_content_resolver,
-          METH_NOARGS,
-          "get_content_resolver(, /)\n--\n\nGet the global resolution manager translating binary contents into loaded contents."
-        },
-        { "get_current_project", py_global_get_current_project,
-          METH_NOARGS,
-          "get_current_project(, /)\n--\n\nGet the current global project."
-        },
-        { "set_current_project", py_global_set_current_project,
-          METH_VARARGS,
-          "set_current_project(, /)\n--\n\nSet the current global project."
-        },
+        GLOBAL_GET_CONTENT_EXPLORER_METHOD,
+        GLOBAL_GET_CONTENT_RESOLVER_METHOD,
+        GLOBAL_GET_CURRENT_PROJECT_METHOD,
+        GLOBAL_SET_CURRENT_PROJECT_METHOD,
         { NULL }
-
     };
 
     module = get_access_to_python_module("pychrysalide.core");
diff --git a/plugins/pychrysalide/core/module.c b/plugins/pychrysalide/core/module.c
index d954821..27113a0 100644
--- a/plugins/pychrysalide/core/module.c
+++ b/plugins/pychrysalide/core/module.c
@@ -55,12 +55,21 @@ bool add_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 core properties through" \
+    " the Python bindings.\n"                                               \
+    "\n"                                                                    \
+    "Most 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_core_module = {
 
         .m_base = PyModuleDef_HEAD_INIT,
 
         .m_name = "pychrysalide.core",
-        .m_doc = "Python module for Chrysalide.core",
+        .m_doc = PYCHRYSALIDE_CORE_DOC,
 
         .m_size = -1,
 
diff --git a/plugins/pychrysalide/core/params.c b/plugins/pychrysalide/core/params.c
index b9d8741..0f23981 100644
--- a/plugins/pychrysalide/core/params.c
+++ b/plugins/pychrysalide/core/params.c
@@ -62,6 +62,16 @@ static PyObject *py_params_get_main_configuration(PyObject *self, PyObject *args
     PyObject *result;                       /* Instance GLib à retourner   */
     GGenConfig *config;                     /* Configuration à convertir   */
 
+#define PARAMS_GET_MAIN_CONFIGURATION_METHOD PYTHON_METHOD_DEF  \
+(                                                               \
+    get_main_configuration, "",                                 \
+    METH_NOARGS, py_params,                                     \
+    "Give access to the main configuration of Chrysalide."      \
+    "\n"                                                        \
+    "The returned object is an instance of type"                \
+    " pychrysalide.glibext.GenConfig."                          \
+)
+
     config = get_main_configuration();
 
     result = pygobject_new(G_OBJECT(config));
@@ -120,13 +130,8 @@ bool populate_core_module_with_params(void)
     PyObject *dict;                         /* Dictionnaire dudit module   */
 
     static PyMethodDef py_params_methods[] = {
-
-        { "get_main_configuration", py_params_get_main_configuration,
-          METH_NOARGS,
-          "get_main_configuration(, /)\n--\n\nGive access to the main configuration of Chrysalide."
-        },
+        PARAMS_GET_MAIN_CONFIGURATION_METHOD,
         { NULL }
-
     };
 
     module = get_access_to_python_module("pychrysalide.core");
diff --git a/plugins/pychrysalide/core/processors.c b/plugins/pychrysalide/core/processors.c
index 47e4643..bd4a50f 100644
--- a/plugins/pychrysalide/core/processors.c
+++ b/plugins/pychrysalide/core/processors.c
@@ -41,10 +41,10 @@
 
 
 /* Enregistre un processeur pour une architecture donnée. */
-static PyObject *py_processors_register_type(PyObject *, PyObject *);
+static PyObject *py_processors_register_processor(PyObject *, PyObject *);
 
 /* Fournit le processeur d'architecture correspondant à un nom. */
-static PyObject *py_processors_get_for_key(PyObject *, PyObject *);
+static PyObject *py_processors_get_processor_for_key(PyObject *, PyObject *);
 
 
 
@@ -61,7 +61,7 @@ static PyObject *py_processors_get_for_key(PyObject *, PyObject *);
 *                                                                             *
 ******************************************************************************/
 
-static PyObject *py_processors_register_type(PyObject *self, PyObject *args)
+static PyObject *py_processors_register_processor(PyObject *self, PyObject *args)
 {
     PyObject *result;                       /* Bilan à retourner           */
     PyObject *type;                         /* Type d'une instance future  */
@@ -72,6 +72,15 @@ static PyObject *py_processors_register_type(PyObject *self, PyObject *args)
     GType instance;                         /* Type pour futures instances */
     bool status;                            /* Bilan d'un enregistrement   */
 
+#define PROCESSORS_REGISTER_PROCESSOR_METHOD PYTHON_METHOD_DEF           \
+(                                                                           \
+    register_processor, "inst, /",                                          \
+    METH_VARARGS, py_processors,                                            \
+    "Register an architecture processor using an initial instance of it.\n" \
+    "\n"                                                                    \
+    "This instance has to be a subclass of pychrysalide.arch.ArchProcessor."\
+)
+
     ret = PyArg_ParseTuple(args, "O!", &PyType_Type, &type);
     if (!ret) return NULL;
 
@@ -130,17 +139,27 @@ static PyObject *py_processors_register_type(PyObject *self, PyObject *args)
 *                                                                             *
 ******************************************************************************/
 
-static PyObject *py_processors_get_for_key(PyObject *self, PyObject *args)
+static PyObject *py_processors_get_processor_for_key(PyObject *self, PyObject *args)
 {
     PyObject *result;                       /* Bilan à retourner           */
-    const char *name;                       /* Nom technique de processeur */
+    const char *key;                        /* Nom technique de processeur */
     int ret;                                /* Bilan de lecture des args.  */
     GArchProcessor *proc;                   /* Instance mise en place      */
 
-    ret = PyArg_ParseTuple(args, "s", &name);
+#define PROCESSORS_GET_PROCESSOR_FOR_KEY_METHOD PYTHON_METHOD_DEF           \
+(                                                                           \
+    get_processor_for_key, "key, /",                                        \
+    METH_VARARGS, py_processors,                                            \
+    "Provide an instance of an architecture processor for a given name,"    \
+    " provided as a key string.\n"                                          \
+    "\n"                                                                    \
+    "The return instance is a pychrysalide.arch.ArchProcessor subclass."    \
+)
+
+    ret = PyArg_ParseTuple(args, "s", &key);
     if (!ret) return NULL;
 
-    proc = get_arch_processor_for_key(name);
+    proc = get_arch_processor_for_key(key);
 
     if (proc != NULL)
     {
@@ -176,18 +195,9 @@ bool populate_core_module_with_processors(void)
     PyObject *module;                       /* Module à recompléter        */
 
     static PyMethodDef py_processors_methods[] = {
-        {
-            "register_processor", py_processors_register_type,
-            METH_VARARGS,
-            "register_processor(name, desc, cls, /)\n--\n\nRegister an an architecture processor by its name, description and class type."
-        },
-        {
-            "get_processor_for_key", py_processors_get_for_key,
-            METH_VARARGS,
-            "get_processor_for_key(name, /)\n--\n\nProvide an instance of an architecture processor for a given name."
-        },
+        PROCESSORS_REGISTER_PROCESSOR_METHOD,
+        PROCESSORS_GET_PROCESSOR_FOR_KEY_METHOD,
         { NULL }
-
     };
 
     module = get_access_to_python_module("pychrysalide.core");
diff --git a/plugins/pychrysalide/core/queue.c b/plugins/pychrysalide/core/queue.c
index 8917712..cc76b77 100644
--- a/plugins/pychrysalide/core/queue.c
+++ b/plugins/pychrysalide/core/queue.c
@@ -58,6 +58,13 @@ static PyObject *py_queue_wait_for_all_global_works(PyObject *self, PyObject *ar
 {
     PyThreadState *_save;                   /* Sauvegarde de contexte      */
 
+#define QUEUE_WAIT_FOR_ALL_GLOBAL_WORKS_METHOD PYTHON_METHOD_DEF    \
+(                                                                   \
+    wait_for_all_global_works, "",                                  \
+    METH_NOARGS, py_queue,                                          \
+    "Wait for all global tasks being processed."                    \
+)
+
     Py_UNBLOCK_THREADS;
 
     wait_for_all_global_works();
@@ -87,13 +94,8 @@ bool populate_core_module_with_queue(void)
     PyObject *module;                       /* Module à recompléter        */
 
     static PyMethodDef py_queue_methods[] = {
-
-        { "wait_for_all_global_works", py_queue_wait_for_all_global_works,
-          METH_NOARGS,
-          "wait_for_all_global_works(, /)\n--\n\nWait for all tasks being processed."
-        },
+        QUEUE_WAIT_FOR_ALL_GLOBAL_WORKS_METHOD,
         { NULL }
-
     };
 
     module = get_access_to_python_module("pychrysalide.core");