Refreshed the Python documentation for the demanglers.

6 files changed, 77 insertions, 16 deletions

diff --git a/plugins/dexbnf/python/demangler.c b/plugins/dexbnf/python/demangler.c
index 60d751b..5084204 100644
--- a/plugins/dexbnf/python/demangler.c
+++ b/plugins/dexbnf/python/demangler.c
@@ -60,6 +60,17 @@ static PyObject *py_dex_demangler_new(PyTypeObject *type, PyObject *args, PyObje
     PyObject *result;                       /* Instance à retourner        */
     GCompDemangler *demangler;              /* Instance à transposer       */
 
+#define DEX_DEMANGLER_DOC                                                       \
+    "DexDemangler is an implementation of a demangler suitable for processing"  \
+    " Dex files.\n"                                                             \
+    "\n"                                                                        \
+    "Instances can be created using the following constructor:\n"               \
+    "\n"                                                                        \
+    "    DexDemangler()"                                                        \
+    "\n"                                                                        \
+    "The Android BNF-style definitions for mangled names is available at:"      \
+    " https://source.android.com/devices/tech/dalvik/dex-format#string-syntax."
+
     demangler = g_dex_demangler_new();
 
     result = pygobject_new(G_OBJECT(demangler));
@@ -102,7 +113,7 @@ PyTypeObject *get_python_dex_demangler_type(void)
 
         .tp_flags       = Py_TPFLAGS_DEFAULT,
 
-        .tp_doc         = "PyChrysalide Dex demangler",
+        .tp_doc         = DEX_DEMANGLER_DOC,
 
         .tp_methods     = py_dex_demangler_methods,
         .tp_getset      = py_dex_demangler_getseters,
diff --git a/plugins/itanium/python/demangler.c b/plugins/itanium/python/demangler.c
index 1838aa1..ee49ade 100644
--- a/plugins/itanium/python/demangler.c
+++ b/plugins/itanium/python/demangler.c
@@ -60,6 +60,17 @@ static PyObject *py_itanium_demangler_new(PyTypeObject *type, PyObject *args, Py
     PyObject *result;                       /* Instance à retourner        */
     GCompDemangler *demangler;              /* Instance à transposer       */
 
+#define ITANIUM_DEMANGLER_DOC                                                   \
+    "ItaniumDemangler is an implementation of a demangler suitable for"         \
+    " processing one kind of C++ mangled names.\n"                              \
+    "\n"                                                                        \
+    "Instances can be created using the following constructor:\n"               \
+    "\n"                                                                        \
+    "    ItaniumDemangler()"                                                    \
+    "\n"                                                                        \
+    "The C++-style name-mangling scheme is available at:"                       \
+    " https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangling."
+
     demangler = g_itanium_demangler_new();
 
     result = pygobject_new(G_OBJECT(demangler));
@@ -102,7 +113,7 @@ PyTypeObject *get_python_itanium_demangler_type(void)
 
         .tp_flags       = Py_TPFLAGS_DEFAULT,
 
-        .tp_doc         = "PyChrysalide Itanium demangler",
+        .tp_doc         = ITANIUM_DEMANGLER_DOC,
 
         .tp_methods     = py_itanium_demangler_methods,
         .tp_getset      = py_itanium_demangler_getseters,
diff --git a/plugins/javadesc/python/demangler.c b/plugins/javadesc/python/demangler.c
index a62ca99..b437c5b 100644
--- a/plugins/javadesc/python/demangler.c
+++ b/plugins/javadesc/python/demangler.c
@@ -60,6 +60,19 @@ static PyObject *py_java_demangler_new(PyTypeObject *type, PyObject *args, PyObj
     PyObject *result;                       /* Instance à retourner        */
     GCompDemangler *demangler;              /* Instance à transposer       */
 
+#define JAVA_DEMANGLER_DOC                                                      \
+    "JavaDemangler is an implementation of a demangler suitable for processing" \
+    " JVM files.\n"                                                             \
+    "\n"                                                                        \
+    "Instances can be created using the following constructor:\n"               \
+    "\n"                                                                        \
+    "    JavaDemangler()"                                                       \
+    "\n"                                                                        \
+    "The descriptors used in the Java VM are described in the Java"             \
+    " specifications ; for instance, for the Java SE 13 Edition, such"          \
+    " descriptors definitions are available at:"                                \
+    " https://docs.oracle.com/javase/specs/jvms/se13/html/jvms-4.html#jvms-4.3."
+
     demangler = g_java_demangler_new();
 
     result = pygobject_new(G_OBJECT(demangler));
@@ -102,7 +115,7 @@ PyTypeObject *get_python_java_demangler_type(void)
 
         .tp_flags       = Py_TPFLAGS_DEFAULT,
 
-        .tp_doc         = "PyChrysalide Java demangler",
+        .tp_doc         = JAVA_DEMANGLER_DOC,
 
         .tp_methods     = py_java_demangler_methods,
         .tp_getset      = py_java_demangler_getseters,
diff --git a/plugins/pychrysalide/format/symbol.c b/plugins/pychrysalide/format/symbol.c
index 66e4dfc..64f4f1f 100644
--- a/plugins/pychrysalide/format/symbol.c
+++ b/plugins/pychrysalide/format/symbol.c
@@ -251,7 +251,7 @@ static int py_binary_symbol_init(PyObject *self, PyObject *args, PyObject *kwds)
 #define BINARY_SYMBOL_DOC                                                       \
     "BinSymbol represents all kinds of symbols, such as strings, routines or"   \
     " objects. If something can be linked to a physical or virtual location,"   \
-    " it can be a symbol."                                                      \
+    " it can be a symbol.\n"                                                    \
     "\n"                                                                        \
     "Instances can be created using the following constructor:\n"               \
     "\n"                                                                        \
diff --git a/plugins/pychrysalide/mangling/demangler.c b/plugins/pychrysalide/mangling/demangler.c
index 15c9c62..d1209d1 100644
--- a/plugins/pychrysalide/mangling/demangler.c
+++ b/plugins/pychrysalide/mangling/demangler.c
@@ -36,6 +36,11 @@
 
 
 
+#define COMPILER_DEMANGLER_DOC                                  \
+    "CompDemangler is an abstract class for demangling names."
+
+
+
 /* Tente de décoder une chaîne de caractères donnée en type. */
 static PyObject *py_compiler_demangler_decode_type(PyObject *, PyObject *);
 
@@ -65,6 +70,16 @@ static PyObject *py_compiler_demangler_decode_type(PyObject *self, PyObject *arg
     GCompDemangler *demangler;              /* Décodeur mis en place       */
     GDataType *type;                        /* Type de données obtenu      */
 
+#define COMPILER_DEMANGLER_DECODED_TYPE_METHOD PYTHON_METHOD_DEF        \
+(                                                                       \
+    decode_type, "$self, desc, /",                                      \
+    METH_VARARGS, py_compiler_demangler,                                \
+    "Demangle a type definition from its string mangled description.\n" \
+    "\n"                                                                \
+    "The result is an instance of type pychrysalide.analysis.DataType"  \
+    " on success, None otherwise."                                      \
+)
+
     ret = PyArg_ParseTuple(args, "s", &desc);
     if (!ret) return NULL;
 
@@ -112,6 +127,16 @@ static PyObject *py_compiler_demangler_decode_routine(PyObject *self, PyObject *
     GCompDemangler *demangler;              /* Décodeur mis en place       */
     GBinRoutine *routine;                   /* Routine obtenue             */
 
+#define COMPILER_DEMANGLER_DECODED_ROUTINE_METHOD PYTHON_METHOD_DEF         \
+(                                                                           \
+    decode_routine, "$self, desc, /",                                       \
+    METH_VARARGS, py_compiler_demangler,                                    \
+    "Demangle a routine definition from its string mangled description.\n"  \
+    "\n"                                                                    \
+    "The result is an instance of type pychrysalide.analysis.BinRoutine"    \
+    " on success, None otherwise."                                          \
+)
+
     ret = PyArg_ParseTuple(args, "s", &desc);
     if (!ret) return NULL;
 
@@ -153,16 +178,8 @@ static PyObject *py_compiler_demangler_decode_routine(PyObject *self, PyObject *
 PyTypeObject *get_python_compiler_demangler_type(void)
 {
     static PyMethodDef py_comp_demangler_methods[] = {
-        {
-            "decode_type", py_compiler_demangler_decode_type,
-            METH_VARARGS,
-            "decode_type(self, desc/)\n--\n\nDemangle a type definition from its string mangled description."
-        },
-        {
-            "decode_routine", py_compiler_demangler_decode_routine,
-            METH_VARARGS,
-            "decode_routine(self, desc/)\n--\n\nDemangle a routine definition from its string mangled description."
-        },
+        COMPILER_DEMANGLER_DECODED_TYPE_METHOD,
+        COMPILER_DEMANGLER_DECODED_ROUTINE_METHOD,
         { NULL }
     };
 
@@ -179,7 +196,7 @@ PyTypeObject *get_python_compiler_demangler_type(void)
 
         .tp_flags       = Py_TPFLAGS_DEFAULT,
 
-        .tp_doc         = "PyChrysalide generic demangler",
+        .tp_doc         = COMPILER_DEMANGLER_DOC,
 
         .tp_methods     = py_comp_demangler_methods,
         .tp_getset      = py_comp_demangler_getseters,
diff --git a/plugins/pychrysalide/mangling/module.c b/plugins/pychrysalide/mangling/module.c
index 2b2aef7..fe9487e 100644
--- a/plugins/pychrysalide/mangling/module.c
+++ b/plugins/pychrysalide/mangling/module.c
@@ -50,12 +50,21 @@ bool add_mangling_module(PyObject *super)
     bool result;                            /* Bilan à retourner           */
     PyObject *module;                       /* Sous-module mis en place    */
 
+#define PYCHRYSALIDE_MANGLING_DOC                                           \
+    "This module provides facilities to decode function or type names"      \
+    " mangled by a compiler.\n"                                             \
+    "\n"                                                                    \
+    "The benefit of using these facilities instead of external tools such"  \
+    " as *c++filt* resides in the quantity of recovered information: not"   \
+    " only the mangled name is restored in a human readable form, but all"  \
+    " the involved inner types get available for further processing."
+
     static PyModuleDef py_chrysalide_mangling_module = {
 
         .m_base = PyModuleDef_HEAD_INIT,
 
         .m_name = "pychrysalide.mangling",
-        .m_doc = "Python module for Chrysalide.mangling",
+        .m_doc = PYCHRYSALIDE_MANGLING_DOC,
 
         .m_size = -1,