From 24398cb372624bf281ee4d9eb07f2a076b3cc664 Mon Sep 17 00:00:00 2001 From: Cyrille Bagard Date: Mon, 6 Jan 2020 00:04:45 +0100 Subject: Refreshed the Python documentation for the demanglers. --- plugins/dexbnf/python/demangler.c | 13 ++++++++++- plugins/itanium/python/demangler.c | 13 ++++++++++- plugins/javadesc/python/demangler.c | 15 +++++++++++- plugins/pychrysalide/format/symbol.c | 2 +- plugins/pychrysalide/mangling/demangler.c | 39 ++++++++++++++++++++++--------- plugins/pychrysalide/mangling/module.c | 11 ++++++++- 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, -- cgit v0.11.2-87-g4458