Updated the documentation for the entry of Python bindings.

2 files changed, 63 insertions, 23 deletions

diff --git a/plugins/pychrysalide/pychrysa.c b/plugins/pychrysalide/pychrysa.c
index 9f0bc20..3bc331c 100644
--- a/plugins/pychrysalide/pychrysa.c
+++ b/plugins/pychrysalide/pychrysa.c
@@ -127,7 +127,20 @@ static void load_python_plugins(GPluginModule *);
 
 static PyObject *py_chrysalide_revision(PyObject *self, PyObject *args)
 {
-    return PyUnicode_FromString("r" XSTR(REVISION));
+    PyObject *result;                       /* Valeur à retourner          */
+
+#define PY_CHRYSALIDE_REVISION_METHOD PYTHON_METHOD_DEF                     \
+(                                                                           \
+     revision, "/",                                                         \
+     METH_NOARGS, py_chrysalide,                                            \
+     "Provide the revision number of Chrysalide.\n"                         \
+     "\n"                                                                   \
+     "The returned value is provided as a string, for instance: 'r1665'."   \
+)
+
+    result = PyUnicode_FromString("r" XSTR(REVISION));
+
+    return result;
 
 }
 
@@ -147,10 +160,20 @@ static PyObject *py_chrysalide_revision(PyObject *self, PyObject *args)
 
 static PyObject *py_chrysalide_version(PyObject *self, PyObject *args)
 {
-    char version[16];
-    int major;
-    int minor;
-    int revision;
+    PyObject *result;                       /* Valeur à retourner          */
+    int major;                              /* Numéro de version majeur    */
+    int minor;                              /* Numéro de version mineur    */
+    int revision;                           /* Numéro de révision          */
+    char version[16];                       /* Conservation temporaire     */
+
+#define PY_CHRYSALIDE_VERSION_METHOD PYTHON_METHOD_DEF                      \
+(                                                                           \
+     version, "/",                                                          \
+     METH_NOARGS, py_chrysalide,                                            \
+     "Provide the version number of Chrysalide.\n"                          \
+     "\n"                                                                   \
+     "The returned value is provided as a string, for instance: '1.6.65'."  \
+)
 
     major = REVISION / 1000;
     minor = (REVISION - (major * 1000)) / 100;
@@ -158,7 +181,9 @@ static PyObject *py_chrysalide_version(PyObject *self, PyObject *args)
 
     snprintf(version, sizeof(version), "%d.%d.%d", major, minor, revision);
 
-    return PyUnicode_FromString(version);
+    result = PyUnicode_FromString(version);
+
+    return result;
 
 }
 
@@ -178,11 +203,23 @@ static PyObject *py_chrysalide_version(PyObject *self, PyObject *args)
 
 static PyObject *py_chrysalide_mod_version(PyObject *self, PyObject *args)
 {
-    char version[16];
+    PyObject *result;                       /* Valeur à retourner          */
+    char version[16];                       /* Conservation temporaire     */
+
+#define PY_CHRYSALIDE_MOD_VERSION_METHOD PYTHON_METHOD_DEF                  \
+(                                                                           \
+     mod_version, "/",                                                      \
+     METH_NOARGS, py_chrysalide,                                            \
+     "Provide the version number of Chrysalide module for Python.\n"        \
+     "\n"                                                                   \
+     "The returned value is provided as a string, for instance: '0.1.0'."   \
+)
 
     snprintf(version, sizeof(version), "%s", _chrysalide_plugin.version);
 
-    return PyUnicode_FromString(version);
+    result = PyUnicode_FromString(version);
+
+    return result;
 
 }
 
@@ -410,21 +447,10 @@ PyMODINIT_FUNC PyInit_pychrysalide(void)
     PluginStatusFlags self_flags;           /* Fanions à mettre à jour     */
 
     static PyMethodDef py_chrysalide_methods[] = {
-
-        { "revision", py_chrysalide_revision,
-          METH_NOARGS,
-          "revision(/)\n--\n\nProvide the revision number of Chrysalide."
-        },
-        { "version", py_chrysalide_version,
-          METH_NOARGS,
-          "version(/)\n--\n\nProvide the version number of Chrysalide."
-        },
-        { "mod_version", py_chrysalide_mod_version,
-          METH_NOARGS,
-          "mod_version(/)\n--\n\nProvide the version number of Chrysalide module for Python."
-        },
+        PY_CHRYSALIDE_REVISION_METHOD,
+        PY_CHRYSALIDE_VERSION_METHOD,
+        PY_CHRYSALIDE_MOD_VERSION_METHOD,
         { NULL }
-
     };
 
     static PyModuleDef py_chrysalide_module = {
diff --git a/plugins/pychrysalide/struct.c b/plugins/pychrysalide/struct.c
index d4d6a9f..e7dbdcd 100644
--- a/plugins/pychrysalide/struct.c
+++ b/plugins/pychrysalide/struct.c
@@ -30,6 +30,20 @@
 
 
 
+#define STRUCT_OBJ_DOC                                                          \
+    "PyStructObject is a sugar glue used to transmit C structures to Python."   \
+    "\n"                                                                        \
+    "For instance, let's consider the following C structure :\n"                \
+    "\n"                                                                        \
+    "    struct _my_struct_t { int a; int b } var;\n"                           \
+    "\n"                                                                        \
+    "Such a structure will be translated into a Python dictionary.\n"           \
+    "\n"                                                                        \
+    "Each previous field gets then accessible using :\n"                        \
+    "* a direct access: *var.a*;\n"                                             \
+    "* an access by name thanks to the dictionary: *var['b']*."
+
+
 /* Objet à vocation abstraite */
 typedef struct _PyStructObject
 {
@@ -119,7 +133,7 @@ PyTypeObject *get_python_py_struct_type(void)
 
         .tp_flags       = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
 
-        .tp_doc         = "PyChrysalide structure",
+        .tp_doc         = STRUCT_OBJ_DOC,
 
         .tp_methods     = py_struct_methods,
         .tp_getset      = py_struct_getseters,