From 90b8f66eb8ae62d951dfbd333fb338e38874c9fe Mon Sep 17 00:00:00 2001
From: Cyrille Bagard <nocbos@gmail.com>
Date: Mon, 23 Dec 2019 00:24:32 +0100
Subject: Updated the documentation for the entry of Python bindings.
---
plugins/pychrysalide/pychrysa.c | 70 ++++++++++++++++++++++++++++-------------
plugins/pychrysalide/struct.c | 16 +++++++++-
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,
--
cgit v0.11.2-87-g4458