diff --git a/Doxyfile.mk b/Doxyfile.mk index 790b866..2ae0d26 100644 --- a/Doxyfile.mk +++ b/Doxyfile.mk @@ -46,13 +46,13 @@ INLINE_GROUPED_CLASSES = NO INLINE_SIMPLE_STRUCTS = NO TYPEDEF_HIDES_STRUCT = NO LOOKUP_CACHE_SIZE = 0 -EXTRACT_ALL = YES -EXTRACT_PRIVATE = NO -EXTRACT_PACKAGE = NO -EXTRACT_STATIC = NO +EXTRACT_ALL = NO +EXTRACT_PRIVATE = YES +EXTRACT_PACKAGE = YES +EXTRACT_STATIC = YES EXTRACT_LOCAL_CLASSES = YES -EXTRACT_LOCAL_METHODS = NO -EXTRACT_ANON_NSPACES = NO +EXTRACT_LOCAL_METHODS = YES +EXTRACT_ANON_NSPACES = YES HIDE_UNDOC_MEMBERS = NO HIDE_UNDOC_CLASSES = NO HIDE_FRIEND_COMPOUNDS = NO @@ -83,7 +83,7 @@ QUIET = NO WARNINGS = YES WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES -WARN_NO_PARAMDOC = NO +WARN_NO_PARAMDOC = YES WARN_AS_ERROR = NO WARN_FORMAT = "$file:$line: $text" INPUT = ./ @@ -151,7 +151,6 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES CLANG_ASSISTED_PARSING = NO ALPHABETICAL_INDEX = YES -COLS_IN_ALPHA_INDEX = 5 GENERATE_HTML = YES HTML_OUTPUT = html HTML_FILE_EXTENSION = .html @@ -199,14 +198,12 @@ PDF_HYPERLINKS = YES USE_PDFLATEX = YES LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO -LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain LATEX_TIMESTAMP = NO GENERATE_RTF = NO RTF_OUTPUT = rtf COMPACT_RTF = NO RTF_HYPERLINKS = NO -RTF_SOURCE_CODE = NO GENERATE_MAN = YES MAN_OUTPUT = man MAN_EXTENSION = .3 @@ -216,7 +213,6 @@ XML_OUTPUT = xml XML_PROGRAMLISTING = YES GENERATE_DOCBOOK = NO DOCBOOK_OUTPUT = docbook -DOCBOOK_PROGRAMLISTING = NO GENERATE_AUTOGEN_DEF = NO GENERATE_PERLMOD = NO PERLMOD_LATEX = NO @@ -229,8 +225,6 @@ SKIP_FUNCTION_MACROS = YES ALLEXTERNALS = NO EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES -PERL_PATH = /usr/bin/perl -CLASS_DIAGRAMS = YES HIDE_UNDOC_RELATIONS = YES HAVE_DOT = YES DOT_NUM_THREADS = 0 diff --git a/config.h b/config.h index 9ef7ba2..994dd9d 100644 --- a/config.h +++ b/config.h @@ -19,12 +19,21 @@ #ifndef __RPN_CONFIG__ #define __RPN_CONFIG__ +/**@file config.h + * @brief Global definition for all C files + */ + +/**@brief The programms is under GPL */ #define _GNU_SOURCE - -#define PYRPN_doc_meth(NAME, header, docstring) PyDoc_STRVAR(NAME ## _doc,\ - header "\n--\n\n" docstring); - +/**@brief Allow fancy method declaration by indicating arguments list + * explicitly + * @param name char* The method name + * @param callback The C function to call + * @param flags int Python flags for method call options + * @param header char* List of arguments + * @param docstring char* The method documentation + */ #define PYRPN_method(name, callback, flags, header, docstring) \ {name, (PyCFunction)callback, flags, \ PyDoc_STR(name "("header ")\n--\n\n" docstring)} diff --git a/python_const.c b/python_const.c index 3ee7be5..359a0bd 100644 --- a/python_const.c +++ b/python_const.c @@ -1,4 +1,11 @@ #include "python_const.h" +/**@file python_const.c + * @brief pyrpn.const code + * @ingroup python_ext + * @ingroup pymod_pyrpn_RPNIterParams + * @ingroup pymod_pyrpn_RPNTokenTypes + * @ingroup pymod_pyrpn_RPNMutationParams + */ /** @todo implement GC with m_clear */ PyModuleDef rpnconstmodule = { @@ -13,6 +20,8 @@ PyModuleDef rpnconstmodule = { }; /* Various named tuple definition, instanciated in python_rpnexpr module init */ +/**@brief @ref pymod_pyrpn_RPNIterParams fields definition + * @ingroup pymod_pyrpn_RPNIterParams */ static PyStructSequence_Field params_fields[] = { { .name = "argc", @@ -43,6 +52,8 @@ PyStructSequence_Desc rpnif_params_desc = { }; PyTypeObject rpnif_params_SeqDesc; +/**@brief @ref pymod_pyrpn_RPNTokenTypes field definition + * @ingroup pymod_pyrpn_RPNTokenTypes */ static PyStructSequence_Field token_types_fields[] = { { .name = "op", .doc = "Operation", @@ -62,6 +73,8 @@ PyStructSequence_Desc rpn_token_types_desc = { }; PyTypeObject rpn_token_types_SeqDesc; +/**@brief @ref pymod_pyrpn_RPNMutationParams field definition + * @ingroup pymod_pyrpn_RPNMutationParams */ static PyStructSequence_Field mutation_params_fields[] = { { .name = "minimum_length", .doc = "Expression minimum length", @@ -106,6 +119,12 @@ rpn_mutation_params_t rpn_mutation_params_default = { .w_mut_elt = {1.0,1.0,1.0}, }; +/**@brief Adds a constant to @ref pymod_pyrpn_const module + * @param mod The @ref pymod_pyrpn_const module + * @param name The constant's name + * @param value The constant's value + * @return 0 or -1 on error + */ int Py_rpnconst_add(PyObject* mod, const char* name, int value) { PyObject *val; @@ -119,7 +138,9 @@ int Py_rpnconst_add(PyObject* mod, const char* name, int value) return 0; } -/** @todo rename this function ! (bad prefix) */ +/**@todo rename this function ! (bad prefix) + * @brief Module initialisation function + * @return The initialized module */ PyObject *Py_rpnconst_init(void) { PyObject *mod; diff --git a/python_const.h b/python_const.h index 9789956..0a5d358 100644 --- a/python_const.h +++ b/python_const.h @@ -30,24 +30,56 @@ #include "rpn_mutate.h" #include "rpn_if_default.h" +/**@file python_const.h + * @brief Python pyrpn.const module headers + * @ingroup python_ext + * @ingroup pymod_pyrpn_const + */ + +/**@defgroup pymod_pyrpn_const module pyrpn.const + * @brief A module containing constant values + * + * Constants values are @ref ifs_if_default_posflag + * and @ref ifs_if_default_resflag + * @ingroup pymod_pyrpn + */ + /**@brief pyrpn.const module specs - * @ingroup python_module */ + * @ingroup pymod_pyrpn */ extern PyModuleDef rpnconstmodule; -/**@brief A single instance of this object is used for parameters representation */ +/**@defgroup pymod_pyrpn_RPNIterParams pyrpn.RPNIterParams + * @brief namedtuple representing @ref pymod_pyrpn_RPNExprIter parameters + * @ingroup pymod_pyrpn */ +/**@brief RPNIterParams named tuple for RPNIterExpr parameters + * @ingroup pymod_pyrpn_RPNIterParams */ extern PyTypeObject rpnif_params_SeqDesc; +/**@brief @ref rpnif_params_SeqDesc named tuple description + * @ingroup pymod_pyrpn_RPNIterParams */ extern PyStructSequence_Desc rpnif_params_desc; +/**@defgroup pymod_pyrpn_RPNTokenTypes pyrpn.RPNTokenTypes + * @brief namedtuple with @ref pymod_pyrpn_token_Token subclass + * @ingroup pymod_pyrpn */ +/**@brief RPNTokenTypes named tuple with token types */ extern PyTypeObject rpn_token_types_SeqDesc; +/**@brief @ref rpn_token_types_SeqDesc named tuple description */ extern PyStructSequence_Desc rpn_token_types_desc; +/**@defgroup pymod_pyrpn_RPNMutationParams pyrpn.RPNMutationParams + * @brief namedtuple storing mutation parameters + * @ingroup pymod_pyrpn */ +/**@brief RPNMutationParams named tuple with mutation parameters */ extern PyTypeObject rpn_mutation_params_SeqDesc; +/**@brief @ref rpn_mutation_params_SeqDesc named tuple description */ extern PyStructSequence_Desc rpn_mutation_params_desc; +/**@brief Default values for mutations parameters */ extern rpn_mutation_params_t rpn_mutation_params_default; /**@brief pyrpn.const module initialisation function - * @ingroup python_module */ + * @return The initialized module + * @ingroup pymod_pyrpn */ PyObject *Py_rpnconst_init(void); #endif diff --git a/python_if.c b/python_if.c index ba1e125..c9b5893 100644 --- a/python_if.c +++ b/python_if.c @@ -1,5 +1,12 @@ #include "python_if.h" +/**@file python_if.c + * @brief Python RPNIterExpr type definition + * @ingroup python_ext + * @ingroup pymod_pyrpn_RPNExprIter + */ +/**@brief @ref pymod_pyrpn_RPNExprIter methods definition + * @ingroup pymod_pyrpn_RPNExprIter */ static PyMethodDef RPNIterExpr_methods[] = { PYRPN_method("get_params", rpnif_get_params, METH_NOARGS, @@ -33,29 +40,38 @@ static PyMethodDef RPNIterExpr_methods[] = { {NULL} //Sentinel }; +/**@brief @ref pymod_pyrpn_RPNExprIter members definition + * @ingroup pymod_pyrpn_RPNExprIter */ static PyMemberDef RPNIterExpr_members[] = { {"expressions", T_OBJECT, offsetof(PyRPNIterExpr_t, expr), READONLY, "The tuple of expressions"}, {NULL} }; +/**@brief @ref pymod_pyrpn_RPNExprIter sequence methods definition + * @ingroup pymod_pyrpn_RPNExprIter */ static PySequenceMethods RPNIterExpr_seq_methods = { .sq_length = rpnif_len, .sq_item = rpnif_expr_item, .sq_ass_item = rpnif_expr_ass_item, }; +/**@brief @ref pymod_pyrpn_RPNExprIter mapping methods definition + * @ingroup pymod_pyrpn_RPNExprIter */ static PyMappingMethods RPNIterExpr_mapping_methods = { .mp_length = rpnif_len, .mp_subscript = rpnif_subscript, .mp_ass_subscript = rpnif_ass_subscript, }; +/**@brief @ref pymod_pyrpn_RPNExprIter attributes definition + * @ingroup pymod_pyrpn_RPNExprIter */ static PyGetSetDef RPNIterExpr_getset[] = { {NULL} }; -// Allows manipulation from numpy +/**@brief @ref pymod_pyrpn_RPNExprIter buffer methods definition + * @ingroup pymod_pyrpn_RPNExprIter */ static PyBufferProcs RPNIterExpr_as_buffer = { (getbufferproc)rpnif_getbuffer, (releasebufferproc)rpnif_releasebuffer, @@ -570,6 +586,11 @@ int rpnif_expr_ass_item(PyObject *self, Py_ssize_t idx, PyObject* elt) return 0; } +/** Convert key to integer index + * @param self @ref PyRPNIterExpr_t instance + * @param _key An expression name (str) + * @return The expression index or -1 on error (raise python exception) + */ static Py_ssize_t _rpnif_subscript_idx(PyObject *self, PyObject *_key) { if(!PyUnicode_Check(_key)) @@ -822,7 +843,9 @@ PyObject* rpnif_str(PyObject *self) return buf; } - +/** Return a string representation of expressions dict + * @param self @ref PyRPNIterExpr_t instance + * @return a str instance */ static PyObject* _rpnif_expr_repr(PyObject *self) { PyRPNIterExpr_t *expr_self = (PyRPNIterExpr_t*)self; @@ -986,3 +1009,10 @@ PyObject* rpnif_setstate(PyObject *self, PyObject *state_bytes) Py_RETURN_NONE; } +/**@def _ret_append(key) + * @hiderefs + * local macro */ +/**@def _const_res_key() + * @hiderefs + * local macro*/ + diff --git a/python_if.h b/python_if.h index 7562324..9f4862e 100644 --- a/python_if.h +++ b/python_if.h @@ -32,8 +32,16 @@ #include "python_rpnexpr.h" #include "python_const.h" -/**@defgroup python_if RPN Iterated Function Python class - * @ingroup python_module +/**@file python_if.h + * @brief Python RPNIterExpr type headers + * @ingroup python_ext + * @ingroup pymod_pyrpn_RPNExprIter + * + * This file is the header of the RPNIterExpr Python class + */ + +/**@defgroup pymod_pyrpn_RPNExprIter class pyrpn.RPNExprIter + * @ingroup pymod_pyrpn * @brief Exposed Python class : RPNIterExpr * * Iterated expression are composed of RPN expressions, they are able to @@ -43,21 +51,15 @@ * @see ifs_if */ -/**@file python_if.h - * @brief Python RPNIterExpr type headers - * @ingroup python_if - * - * This file is the header of the RPNIterExpr Python class - */ - /**@brief RPNIterExpr Python class type definition - * @ingroup python_if */ + * @ingroup pymod_pyrpn_RPNExprIter */ extern PyTypeObject RPNIterExprType; /**@brief Structure holding RPNIterExpr objects - * @ingroup python_if */ + * @ingroup pymod_pyrpn_RPNExprIter */ typedef struct { + /** Python's type definition */ PyObject_VAR_HEAD; /** @brief Number of dimention in map */ @@ -74,8 +76,9 @@ typedef struct /**@brief RpnIterExpr __new__ method * @param subtype Type of object being created (pyrpn.RPNIterExpr) * @param args positional arguments for subtype - * @param kwargs keyword argumenrs for subtype + * @param kwds keyword argumenrs for subtype * @return The new Python RPNIterExpr object + * @ingroup pymod_pyrpn_RPNExprIter */ PyObject* rpnif_new(PyTypeObject *subtype, PyObject* args, PyObject* kwds); @@ -84,35 +87,57 @@ PyObject* rpnif_new(PyTypeObject *subtype, PyObject* args, PyObject* kwds); * @param args Positional arguments list * @param kwds Keywords arguments dict * @return 0 if no error else -1 - * @ingroup python_if + * @ingroup pymod_pyrpn_RPNExprIter */ int rpnif_init(PyObject *self, PyObject *args, PyObject *kwds); /**@brief RPNIterExpr __del__ method * @param self RPNExpr instance - * @ingroup python_type + * @ingroup pymod_pyrpn_RPNExprIter */ void rpnif_del(PyObject *self); -/**@brief Buffer protocol request handler method */ +/**@brief Buffer protocol request handler method + * @param self RPNIterExpr instance + * @param view A memoryview to fill depending on flags + * @param flags Indicates the request type + * @return -1 on error + * See python documentation at + * https://docs.python.org/3/c-api/buffer.html#buffer-request-types + * @ingroup pymod_pyrpn_RPNExprIter + */ int rpnif_getbuffer(PyObject *self, Py_buffer *view, int flags); -/**@brief Buffer protocol request release method */ + +/**@brief Buffer protocol request release method + * @param self RPNIterExppr instance + * @param view The memoryview to release (free what we filled) + * See python documentation at + * https://docs.python.org/3/c-api/buffer.html#buffer-request-types + * @ingroup pymod_pyrpn_RPNExprIter + */ void rpnif_releasebuffer(PyObject *self, Py_buffer *view); -/**@brief Return a named tuple of custom rif data */ +/**@brief Return a named tuple of custom rif data + * @param self RPNIterExpr instance + * @return A RPNIterParams named tuple + * @ingroup pymod_pyrpn_RPNExprIter + */ PyObject *rpnif_get_params(PyObject *self); -/**@brief Runs an if on given */ +/**@brief Runs an IF on given position + * @param self RPNInterExpr instance + * @param pos The start position + * @return A new position + * @ingroup pymod_pyrpn_RPNExprIter + */ PyObject *rpnif_step(PyObject *self, PyObject* pos); -/**@brief Return the list of expressions */ -PyObject *rpnif_get_expr(PyObject *self); - /**@brief RPNIterExpr __getstate__ method for pickling * @param cls RPNIterExpr type object * @param noargs Not an argument... * @return A bytes Python instance suitable as argument for * @ref rpnexpr_setstate + * @ingroup pymod_pyrpn_RPNExprIter */ PyObject* rpnif_getstate(PyObject *cls, PyObject *noargs); @@ -122,35 +147,85 @@ PyObject* rpnif_getstate(PyObject *cls, PyObject *noargs); * rpnexpr_getstate * @return A bytes Python instance suitable as argument for * @ref rpnexpr_setstate + * @ingroup pymod_pyrpn_RPNExprIter */ PyObject* rpnif_setstate(PyObject *cls, PyObject *state); /**@brief RPNIterExpr.__repr__() * @param self RPNIterExpr instance - * @ingroup python_type + * @return A string representation of the instance + * @ingroup pymod_pyrpn_RPNExprIter */ PyObject* rpnif_repr(PyObject *self); /**@brief RPNIterExpr.__str__() * @param self RPNIterExpr instance - * @ingroup python_type + * @return A string representation of the instance + * @ingroup pymod_pyrpn_RPNExprIter */ PyObject* rpnif_str(PyObject *self); /**@brief RPNExpr.__len__() method + * @param self RPNIterExpr instance * @return A integer with the number of tokens in expression + * @ingroup pymod_pyrpn_RPNExprIter */ Py_ssize_t rpnif_len(PyObject *self); -PyObject* rpnif_expr_item(PyObject *self, Py_ssize_t); +/**@brief Sequence method for __getitem__ method + * + * Allow expressions access with integer indexes + * @param self RPNIterExpr instance + * @param idx Item index + * @return Corresponding RPNExpr or raise IndexError + * @ingroup pymod_pyrpn_RPNExprIter + */ +PyObject* rpnif_expr_item(PyObject *self, Py_ssize_t idx); + +/**@brief Sequence method for __setitem__ method + * + * Allow to recompile an expressions using a str with integer indexes + * @param self RPNIterExpr instance + * @param idx Item index + * @param elt The code (str) to compile in indicated expression + * @return 0 if no error else -1 + * @ingroup pymod_pyrpn_RPNExprIter + */ int rpnif_expr_ass_item(PyObject *self, Py_ssize_t idx, PyObject* elt); - +/**@brief Mapping method to access expressions by name + * @param self RPNIterExpr instance + * @param key An expression name (depending on parameters) + * @return The corresponding RPNExpr of raise KeyError + * @ingroup pymod_pyrpn_RPNExprIter + */ PyObject* rpnif_subscript(PyObject *self, PyObject *key); + +/**@brief Mapping method to recompile an expression by name + * @param self RPNIterExpr instance + * @param key An expression name (depending on parameters) + * @param elt The code (str) to compile in indicated expression + * @return 0 if no error else -1 + * @ingroup pymod_pyrpn_RPNExprIter + */ int rpnif_ass_subscript(PyObject *self, PyObject *key, PyObject *elt); +/**@brief Mimics dict.keys() method + * @param self RPNIterExpr instance + * @return A tuple with expressions name + * @ingroup pymod_pyrpn_RPNExprIter */ PyObject *rpnif_keys(PyObject *self); + +/**@brief Mimics dict.values() method + * @param self RPNIterExpr instance + * @return A tuple with RPNExpr instances + * @ingroup pymod_pyrpn_RPNExprIter */ PyObject *rpnif_values(PyObject *self); + +/**@brief Mimics dict.items() method + * @param self RPNIterExpr instance + * @return A tuple with tuples(key, value) + * @ingroup pymod_pyrpn_RPNExprIter */ PyObject *rpnif_items(PyObject *self); diff --git a/python_pyrpn.c b/python_pyrpn.c index 65b76ab..bf24b6d 100644 --- a/python_pyrpn.c +++ b/python_pyrpn.c @@ -21,10 +21,12 @@ /**@file python_pyrpn.c * @brief Python module & type definition * @ingroup python_ext + * @ingroup python_pyrpn * * This file contains pyrpn Python module definition */ +/**@brief pyrpn module's method definition */ static PyMethodDef rpnmodule_methods[] = { PYRPN_method("get_ops", pyrpn_ops, METH_NOARGS, diff --git a/python_pyrpn.h b/python_pyrpn.h index 0ff9847..5b15cbe 100644 --- a/python_pyrpn.h +++ b/python_pyrpn.h @@ -33,8 +33,19 @@ #include "python_const.h" #include "python_rpntoken.h" -/**@defgroup python_ext Python API - * @brief Python API definitions +/**@file python_pyrpn.h + * @brief Python module & type headers + * @ingroup python_ext + * @ingroup pymod_pyrpn + * + * This file is the header of the pyrpn Python module definition + */ + +/**@defgroup python_ext Python extension + * @brief RPNIFS python extension + * + * RPNIFS comes with a python extension module allowing to use the RPN + * expressions in python. * * @ref python_pyrpn.c and @ref python_rpnexpr.c should be compiled in a .so file * in order to expose a pyrpn Python module. @@ -49,33 +60,28 @@ * - pyrpn.RPNExpr.reset_stack(self) to set all stack items to 0 */ -/**@defgroup python_module pyrpn Python module - * @brief Exposed Python module : pyrpn +/**@defgroup pymod_pyrpn pyrpn Python module + * @brief Python extension main entry-point * @ingroup python_ext */ -/**@file python_pyrpn.h - * @brief Python module & type headers - * @ingroup python_module - * - * This file is the header of the pyrpn Python module definition - */ - +/**@brief RPNExpr Python class type definition */ extern PyTypeObject RPNExprType; /**@brief Python module initialization function - * @ingroup python_module */ + * @return The initialized module + * @ingroup pymod_pyrpn */ PyMODINIT_FUNC PyInit_pyrpn(void); /**@brief Python module specs - * @ingroup python_module */ + * @ingroup pymod_pyrpn */ extern PyModuleDef rpnmodule; /**@brief Return a dict with valid operations (short keys and long values) * @param mod pyrpn module object * @param noargs Dummy argument for METH_NOARG * @return The a new dict - * @ingroup python_module + * @ingroup pymod_pyrpn */ PyObject* pyrpn_ops(PyObject* mod, PyObject* noargs); @@ -83,7 +89,8 @@ PyObject* pyrpn_ops(PyObject* mod, PyObject* noargs); * @param mod pyrpn module object * @param args Position arguments in Python list * @param kwds Keywords arguments in Python dict - * @ingroup python_module + * @return A str instance + * @ingroup pymod_pyrpn */ PyObject* pyrpn_random(PyObject *mod, PyObject *args, PyObject *kwds); diff --git a/python_rpnexpr.c b/python_rpnexpr.c index 6e2275f..a9db239 100644 --- a/python_rpnexpr.c +++ b/python_rpnexpr.c @@ -18,6 +18,14 @@ */ #include "python_rpnexpr.h" +/**@file python_rpnexpr.c + * @brief Python module & type definition + * @ingroup python_ext + * @ingroup python_pyrpn_RPNExpr + */ + +/**@brief @ref pymod_pyrpn_RPNExpr methods definition + * @ingroup python_pyrpn_RPNExpr */ static PyMethodDef RPNExpr_methods[] = { PYRPN_method("random", rpnexpr_random, METH_CLASS | METH_VARARGS | METH_KEYWORDS, @@ -58,11 +66,15 @@ static PyMethodDef RPNExpr_methods[] = { {NULL} //Sentinel }; +/**@brief @ref pymod_pyrpn_RPNExpr members definition + * @ingroup python_pyrpn_RPNExpr */ static PyMemberDef RPNExpr_members[] = { {NULL} }; -/**@todo Continue sequence implementation with contains, concat, repeat etc. */ +/**@brief @ref pymod_pyrpn_RPNExpr methods definition + * @todo Continue sequence implementation with contains, concat, repeat etc. + * @ingroup python_pyrpn_RPNExpr */ static PySequenceMethods RPNExpr_seq_methods = { .sq_length = rpnexpr_len, .sq_item = rpnexpr_token_item, @@ -888,6 +900,11 @@ PyObject* rpnexpr_default_mutation_params(PyObject *cls, PyObject **argv, Py_ssi } +/**@brief Parse given object to float + * @param obj The python object to parse + * @param res Points on result + * @note Raise python exception on error + */ static inline void _parse_float(PyObject *obj, float *res) { double tmp = PyFloat_AsDouble(obj); @@ -900,6 +917,11 @@ static inline void _parse_float(PyObject *obj, float *res) return; } +/** Parse weights python parameter + * @param obj The python object + * @param w Points on the 3 weights to parse + * @note Raise python exception on error + */ static inline void _parse_type_weights(PyObject *obj, float w[3]) { PyObject *fast = PySequence_Fast(obj, "Not a RPNTokenTypeTuple nor with a length of 3"); diff --git a/python_rpnexpr.h b/python_rpnexpr.h index 9619ad2..69ee103 100644 --- a/python_rpnexpr.h +++ b/python_rpnexpr.h @@ -32,27 +32,29 @@ #include "python_rpntoken.h" #include "python_const.h" -/**@defgroup python_type RPNExpr Python class - * @brief Exposed Python class : RPNExpr - * @ingroup python_module - */ - /**@file python_rpnexpr.h - * @brief Python RPNExpr type headers - * @ingroup python_type + * @brief pyrpn.RPNExpr definition + * @ingroup python_ext + * @ingroup pymod_pyrpn_RPNExpr * * This file is the header of the RPNExpr Python class - * */ +/**@defgroup pymod_pyrpn_RPNExpr pyrpn.RPNExpr + * @brief Exposed Python class : RPNExpr + * @ingroup pymod_pyrpn + */ + + /**@brief RPNExpr Python class type definition - * @ingroup python_type */ + * @ingroup pymod_pyrpn_RPNExpr */ extern PyTypeObject RPNExprType; /**@brief Structure holding RPNExpr objects - * @ingroup python_type */ + * @ingroup pymod_pyrpn_RPNExpr */ typedef struct { + /** Python's type definition */ PyObject_VAR_HEAD; /**@brief Pointer on @ref rpn_expr_s */ @@ -69,26 +71,35 @@ typedef struct /**@brief Organize PyRPNExpr_t state data * @see rpnexpr_getstate - * @see rpnexpr_setstate */ + * @see rpnexpr_setstate + * @ingroup pymod_pyrpn_RPNExpr */ typedef struct { + /**@brief The total size of the state */ size_t total_sz; + /**@brief Expression's argument count */ size_t argc; + /**@brief Expression's stack size */ unsigned char stack_sz; + /**@brief Number of tokens in expression */ size_t token_sz; } PyRPNExpr_state_t; /**@brief Return a new instance of RPNExpr with a borrowed expression + * @param borrowed An rpn expression to borrow * @note Borrowed expression means that the rpn_expr_t is handled by someone * else and should not be freed when the instance is deleted + * @return A new RPNExpr instance + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_init_borrowing(rpn_expr_t *borrowed); /**@brief RpnExpr __new__ method * @param subtype Type of object being created (pyrpn.RPNExpr) * @param args positional arguments for subtype - * @param kwargs keyword argumenrs for subtype + * @param kwds keyword argumenrs for subtype * @return The new Python RPNExpr object + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_new(PyTypeObject *subtype, PyObject *args, PyObject* kwds); @@ -97,13 +108,13 @@ PyObject* rpnexpr_new(PyTypeObject *subtype, PyObject *args, PyObject* kwds); * @param args Positional arguments list * @param kwds Keywords arguments dict * @return 0 if no error else -1 - * @ingroup python_type + * @ingroup pymod_pyrpn_RPNExpr */ int rpnexpr_init(PyObject *self, PyObject *args, PyObject *kwds); /**@brief RPNExpr __del__ method * @param self RPNExpr instance - * @ingroup python_type + * @ingroup pymod_pyrpn_RPNExpr */ void rpnexpr_del(PyObject *self); @@ -112,6 +123,7 @@ void rpnexpr_del(PyObject *self); * @param self RPNExpr instance * @param noargs Not an argument... * @return A bytes Python instance + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_getexprstate(PyObject *self, PyObject *noargs); @@ -120,6 +132,7 @@ PyObject* rpnexpr_getexprstate(PyObject *self, PyObject *noargs); * @param noargs Not an argument... * @return A bytes Python instance suitable as argument for * @ref rpnexpr_setstate + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_getstate(PyObject *self, PyObject *noargs); @@ -129,23 +142,41 @@ PyObject* rpnexpr_getstate(PyObject *self, PyObject *noargs); * rpnexpr_getstate * @return A bytes Python instance suitable as argument for * @ref rpnexpr_getstate + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_setstate(PyObject *cls, PyObject *state); /**@brief RPNExpr __copy__ method for cloning - * @param self RPNExpr instance + * @param cls RPNExpr class * @param noargs Not an argument... * @return A new cloned instance * @ref rpnexpr_setstate + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_copy(PyObject *cls, PyObject *noargs); /**@brief RPNExpr.__len__() method + * @param self RPNExpr instance * @return A integer with the number of tokens in expression + * @ingroup pymod_pyrpn_RPNExpr */ Py_ssize_t rpnexpr_len(PyObject *self); -PyObject* rpnexpr_token_item(PyObject *self, Py_ssize_t); +/**@brief Sequence method for __getitem__ token getter + * @param self RPNExpr instance + * @param idx The item index (can be negative) + * @return A @ref RPNTokenType subclass instance + * @ingroup pymod_pyrpn_RPNExpr + */ +PyObject* rpnexpr_token_item(PyObject *self, Py_ssize_t idx); + +/**@brief Sequence method for __setitem__ token setter + * @param self RPNExpr instance + * @param idx The item index + * @param elt An RPNTokenType subclass token to set + * @return 0 or -1 on error and raise IndexError + * @ingroup pymod_pyrpn_RPNExpr + */ int rpnexpr_token_ass_item(PyObject *self, Py_ssize_t idx, PyObject* elt); /**@brief Eval an RPN expression given arguments and return the @@ -154,14 +185,16 @@ int rpnexpr_token_ass_item(PyObject *self, Py_ssize_t idx, PyObject* elt); * @param argv Array of PyObject* arguments * @param argc Number of arguments * @return The value resulting of evaluation - * @ingroup python_type + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_eval(PyObject* self, PyObject** argv, Py_ssize_t argc); /**@brief Mutate an RPN expression given arguments and return the value - * @param PyObject* RPNExpr instance - * @param PyObject* Positionnal arguments - * @param PyObject* Keyword arguments + * @param self RPNExpr instance + * @param args Positionnal arguments + * @param kwds Keyword arguments + * @return Py_None + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_mutate(PyObject* self, PyObject *args, PyObject *kwds); @@ -169,44 +202,56 @@ PyObject* rpnexpr_mutate(PyObject* self, PyObject *args, PyObject *kwds); * @param self RPNExpr instance * @param noargs Dummy argument for METH_NOARG * @return None - * @ingroup python_type + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_reset_stack(PyObject *self, PyObject *noargs); /**@brief RPNExpr.__repr__() * @param self RPNExpr instance - * @ingroup python_type + * @return An str instance representing the exppression + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_repr(PyObject *self); /**@brief RPNExpr.__str__() * @param self RPNExpr instance - * @ingroup python_type + * @return An str instance representing the exppression + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_str(PyObject *self); +/**@brief RPNExpr PEP-207 richcompare method + * @param _self RPNExpr instance + * @param other RPNExpr instance to compare to + * @param op The comparison to be done + * @return Py_True or Py_False + * @ingroup pymod_pyrpn_RPNExpr + */ PyObject* rpnexpr_richcompare(PyObject *_self, PyObject *other, int op); /**@brief Return a new Python str with a random RPN expression - * @param mod pyrpn module object + * @param cls pyrpn module object * @param args Position arguments in Python list * @param kwds Keywords arguments in Python dict - * @ingroup python_module + * @return A str instance + * @ingroup pymod_pyrpn */ PyObject* rpnexpr_random(PyObject *cls, PyObject *args, PyObject *kwds); /**@brief Return a new named tuple containing default mutation parameters - * @param PyObject* The class (class method) - * @param PyObject** The arguments (FASTCALL) - * @param Py_ssize_t The number of arguments + * @param cls The class (class method) + * @param argv The arguments (FASTCALL) + * @param argc The number of arguments * @return The named tuple + * @ingroup pymod_pyrpn_RPNExpr */ PyObject* rpnexpr_default_mutation_params(PyObject *cls, PyObject **argv, Py_ssize_t argc); /**@brief Try to convert a python object into a rpn_mutation_params_t - * @param PyObject* The python object - * @param rpn_mutation_params_t A pointer on the parameters to initialize + * @param py_params The python object + * @param params A pointer on the parameters to initialize * @return -1 on failure and raise an exception + * @ingroup pymod_pyrpn_RPNExpr */ int rpnexpr_pyobj_to_mutation_params(PyObject* py_params, rpn_mutation_params_t *params); diff --git a/python_rpntoken.c b/python_rpntoken.c index 81c4a77..a4d42b0 100644 --- a/python_rpntoken.c +++ b/python_rpntoken.c @@ -1,5 +1,16 @@ #include "python_rpntoken.h" +/**@file python_rpntoken.c + * @brief Python module & type definition + * @ingroup python_ext + * @ingroup python_pyrpn_token + * @ingroup python_pyrpn_token_Token + * @ingroup python_pyrpn_token_TokenOp + * @ingroup python_pyrpn_token_TokenVal + * @ingroup python_pyrpn_token_TokenArg + */ +/**@brief @ref pymod_pyrpn_token_Token method definition + * @ingroup python_pyrpn_token_Token */ static PyMethodDef RPNToken_methods[] = { PYRPN_method("from_str", rpntoken_from_str, METH_CLASS | METH_O, "cls, token_str, /", @@ -22,6 +33,8 @@ PyTypeObject RPNTokenType = { .tp_methods = RPNToken_methods, }; +/**@brief @ref pymod_pyrpn_token_TokenOp method definition + * @ingroup python_pyrpn_token_TokenOp */ static PyMethodDef RPNTokenOp_methods[] = { PYRPN_method("opcode_max", rpntokenop_opcode_max, METH_STATIC | METH_NOARGS, @@ -36,6 +49,8 @@ static PyMethodDef RPNTokenOp_methods[] = { {NULL} // }; +/**@brief @ref pymod_pyrpn_token_TokenOp members definition + * @ingroup python_pyrpn_token_TokenOp */ static PyMemberDef RPNTokenOp_members[] = { {"opcode", T_BYTE, offsetof(RPNTokenOp_t, super.value.op_n), READONLY, "The number representing the operand"}, @@ -61,6 +76,8 @@ PyTypeObject RPNTokenOpType = { .tp_methods = RPNTokenOp_methods, }; +/**@brief @ref pymod_pyrpn_token_TokenArg members definition + * @ingroup python_pyrpn_token_TokenArg */ static PyMemberDef RPNTokenArg_members[] = { {"argno", T_ULONG, offsetof(RPNTokenOp_t, super.value.arg_n), READONLY, "The argument number"}, @@ -79,6 +96,8 @@ PyTypeObject RPNTokenArgType = { .tp_members = RPNTokenArg_members, }; +/**@brief @ref pymod_pyrpn_token_TokenVal members definition + * @ingroup python_pyrpn_token_TokenVal */ static PyMemberDef RPNTokenVal_members[] = { {"value", T_ULONG, offsetof(RPNTokenOp_t, super.value.value), READONLY, "The immediate value"}, diff --git a/python_rpntoken.h b/python_rpntoken.h index 3cc0584..99f25fb 100644 --- a/python_rpntoken.h +++ b/python_rpntoken.h @@ -26,56 +26,186 @@ #include #include "structmember.h" -/**@file python_rpnexpr.h +/**@file python_rpntoken.h * @brief Python RPNToken type headers - * @ingroup python_type + * @ingroup python_ext + * @ingroup pymod_pyrpn_token * * This file is the header of the RPNToken classes and subclasses * */ - -extern PyTypeObject RPNTokenType; -extern PyTypeObject RPNTokenOpType; -extern PyTypeObject RPNTokenValType; -extern PyTypeObject RPNTokenArgType; +/**@defgroup pymod_pyrpn_token module pyrpn.token + * @brief Python module representing RPNExpr tokens + * @ingroup pymod_pyrpn + */ +/**@brief pyrpn.token module */ extern PyModuleDef rpntokens_module; +/**@defgroup pymod_pyrpn_token_Token pyrpn.token.Token + * @brief Abstract class representing an @ref pymod_pyrpn_RPNExpr token + * @ingroup pymod_pyrpn_token */ +/**@brief pyrpn.token.Token generic type + * @ingroup pymod_pyrpn_token_Token */ +extern PyTypeObject RPNTokenType; + +/**@defgroup pymod_pyrpn_token_TokenOp pyrpn.token.TokenOp + * @brief Python class representing an @ref pymod_pyrpn_RPNExpr operation token + * + * Extends @ref pymod_pyrpn_token_Token + * @ingroup pymod_pyrpn_token */ +/**@brief pyrpn.token.TokenOp type + * @ingroup pymod_pyrpn_token_TokenOp */ +extern PyTypeObject RPNTokenOpType; + +/**@defgroup pymod_pyrpn_token_TokenVal pyrpn.token.TokenVal + * @brief Python class representing an @ref pymod_pyrpn_RPNExpr value token + * + * Extends @ref pymod_pyrpn_token_Token + * @ingroup pymod_pyrpn_token */ +/**@brief pyrpn.token.TokenVal type + * @ingroup pymod_pyrpn_token_TokenVal */ +extern PyTypeObject RPNTokenValType; + +/**@defgroup pymod_pyrpn_token_TokenArg pyrpn.token.TokenArg + * @brief Python class representing an @ref pymod_pyrpn_RPNExpr argument token + * + * Extends @ref pymod_pyrpn_token_Token + * @ingroup pymod_pyrpn_token */ +/**@brief pyrpn.token.TokenArg type + * @ingroup pymod_pyrpn_token_TokenArg */ +extern PyTypeObject RPNTokenArgType; + + +/**@brief C representation of @ref RPNTokenType generic class + * @ingroup pymod_pyrpn_token_Token */ typedef struct { + /** Python's type definition */ PyObject_HEAD; + /** @brief The token value (will be set by subtypes) */ rpn_token_t value; } RPNToken_t; +/**@brief C representation of all @ref RPNTokenType subclasses + * @ingroup pymod_pyrpn_token_tokenOp + * @ingroup pymod_pyrpn_token_tokenVal + * @ingroup pymod_pyrpn_token_tokenArg + */ typedef struct { + /** @brief Pointer on super type */ RPNToken_t super; -} RPNTokenOp_t; +} RPNTokenSubClass_t; -typedef struct { - RPNToken_t super; -} RPNTokenVal_t; +/**@brief C representation of @ref RPNTokenOpType + * @ingroup pymod_pyrpn_token_TokenOp */ +typedef RPNTokenSubClass_t RPNTokenOp_t; +/**@brief C representation of @ref RPNTokenValType + * @ingroup pymod_pyrpn_token_TokenVal */ +typedef RPNTokenSubClass_t RPNTokenVal_t; +/**@brief C representation of @ref RPNTokenArgType + * @ingroup pymod_pyrpn_token_TokenArg */ +typedef RPNTokenSubClass_t RPNTokenArg_t; -typedef struct { - RPNToken_t super; -} RPNTokenArg_t; +/**@brief Module initialisation function + * @return initialized module + * @ingroup pymod_pyrpn_token */ PyObject* rpntokens_module_init(void); -PyObject* rpntoken_from_str(PyObject *_self, PyObject *arg); -/** Instanciate a new RPNToken subclass given a token */ +/**@brief Class method returning a token instance from a string representation + * @param cls @ref RPNTokenType class or any subclass + * @param arg A str representing a token + * @return A new @ref RPNTokenType subclass instance or NULL on error + * @ingroup pymod_pyrpn_token_Token + */ +PyObject* rpntoken_from_str(PyObject *cls, PyObject *arg); + +/**@brief Instanciate a new RPNToken subclass given a C token + * @param token An expression token + * @return A new @ref RPNTokenType subclass instance + * @ingroup pymod_pyrpn_token_Token + */ PyObject* rpntoken_from_token(const rpn_token_t *token); + +/**@brief @ref RPNTokenType __init__ method + * @param _self @ref RPNTokenType subclass instance + * @param args Positional arguments + * @param kwds Keyword arguments + * @return 0 or -1 on error + * @ingroup pymod_pyrpn_token_Token + */ int rpntoken_init(PyObject *_self, PyObject *args, PyObject *kwds); + +/**@brief PEP-207 comparison method + * @param _self An @ref RPNTokenType subclass instance + * @param other The @ref RPNTokenType subclass instance to compare to + * @param op The comparison + * @return Py_True or Py_False + * @ingroup pymod_pyrpn_token_Token + */ PyObject* rpntoken_richcompare(PyObject *_self, PyObject *other, int op); + +/**@brief __str__ method + * @param _self An @ref RPNTokenType subclass instance + * @return A str representing the token + * @ingroup pymod_pyrpn_token_Token */ PyObject* rpntoken_str(PyObject *_self); + +/**@brief __repr__ method + * @param _self An @ref RPNTokenType subclass instance + * @return A str representing the token + * @ingroup pymod_pyrpn_token_Token */ PyObject* rpntoken_repr(PyObject *_self); + + + + +/**@brief @ref RPNTokenOpType __init__ method + * @param _self RPNTokenOpType being initialized + * @param args Positional arguments + * @param kwds Keyword arguments + * @return 0 or -1 on error + * @ingroup pymod_pyrpn_token_TokenOp */ int rpntokenop_init(PyObject *_self, PyObject *args, PyObject *kwds); + +/**@brief @ref RPNTokenOpType opcode_max method + * @param Py_UNUSED unused argument for static method + * @return The maximum valid opcode + * @ingroup pymod_pyrpn_token_TokenOp */ PyObject *rpntokenop_opcode_max(PyObject *Py_UNUSED(_static)); + +/**@brief @ref RPNTokenOpType chr method + * @param _self @ref RPNTokenOpType instance + * @param Py_UNUSED unused argument + * @return A string with a single chr representing the operation + * @ingroup pymod_pyrpn_token_TokenOp */ PyObject *rpntokenop_opchr(PyObject *_self, PyObject* Py_UNUSED(_null)); + +/**@brief @ref RPNTokenOpType str method + * @param _self @ref RPNTokenOpType instance + * @param Py_UNUSED unused argument + * @return A string representing the operation on multiple chr + * @ingroup pymod_pyrpn_token_TokenOp */ PyObject *rpntokenop_opstr(PyObject *_self, PyObject* Py_UNUSED(_null)); + +/**@brief @ref RPNTokenValType __init__ method + * @param _self RPNTokenValType being initialized + * @param args Positional arguments + * @param kwds Keyword arguments + * @return 0 or -1 on error + * @ingroup pymod_pyrpn_token_TokenVal */ int rpntokenval_init(PyObject *_self, PyObject *args, PyObject *kwds); + +/**@brief @ref RPNTokenArgType __init__ method + * @param _self RPNTokenArgType being initialized + * @param args Positional arguments + * @param kwds Keyword arguments + * @return 0 or -1 on error + * @ingroup pymod_pyrpn_token_TokenArg */ int rpntokenarg_init(PyObject *_self, PyObject *args, PyObject *kwds); #endif diff --git a/rpn_if.h b/rpn_if.h index 24d6ed4..1b3b5ce 100644 --- a/rpn_if.h +++ b/rpn_if.h @@ -34,12 +34,29 @@ * @ingroup ifs * @brief Iterated RPN expression * - * A single Iterated Function implemented using an RPN expression. + * @note For more details about Iterated function see dedicated + * section : @ref doc_ifs_if * - * @note The goal is to optimize iteration writing the code in C and providing - * an high level Python API. + * Iterated function are function that can be iterated on successive position + * in a memory map. The function takes its arguments from a position in the + * memory map and output its results at a resulting position in the memory map. * - * For more details about IF see dedicated page : @ref doc_ifs_if + * The iterated function can be seen as a function taking a position as argument + * and outputing another position with borders effects from data stored at given + * positions. + * + * The implementation try to be as generic as possible, allowing to implement + * the transformation using a @ref rpn_expr_t system. The iterated function + * has 2 functions as parameters : + * - The first one @ref rpn_if_param_s.getarg_f transform a position + * to argument(s) and fetch the other arguments from the memory map + * - The second @ref rpn_if_param_s.setres_f takes the results from the + * @ref rpn_expr_t system, transform it in position and results and set + * the memory map at resulting position with results. + * + * Based on this generic implementation @ref ifs_if_default are implemented for + * various common cases : mutli-dimentionnal positions and constants, boolean, + * colors as results. */ /**@brief Shortcut for struct @ref rpn_if_s */ @@ -100,7 +117,6 @@ struct rpn_if_s /**@brief Alloc a new @ref rpn_if_s using given parameters * @param params IF parameters - * @param rpn list of RPN expresions of params->rpn_sz size * @param memmap A suitable memory map. If NULL given, a new mmap is used * @return A pointer on an allocated @ref rpn_if_s */ @@ -121,6 +137,7 @@ size_t rpn_if_step(rpn_if_t *rif, size_t pos); /**@brief Returns the list of RPN expression : allowing to recompile them + * @param rif Pointer on IF * @return A list of RPN expressions * @note The memory area returned must not be freed ! */ diff --git a/rpn_if_default.h b/rpn_if_default.h index 45fc58a..e4b3861 100644 --- a/rpn_if_default.h +++ b/rpn_if_default.h @@ -18,6 +18,8 @@ */ #ifndef __rpn_if_default__h__ #define __rpn_if_default__h__ +#include "config.h" +#include "rpn_if.h" /**@file rpn_if_default.h Defines default IF * @ingroup ifs_if_default @@ -25,17 +27,19 @@ * @brief Default IF definitions */ -/**@defgroup ifs_if_default Default functions +/**@defgroup ifs_if_default Default iterated functions * @ingroup ifs_if - * @brief Simple iterated functions functions + * @brief Iterated function default implementation * - * Defines default @ref rpn_if_param_s.res_f and @ref rpn_if_param_s.arg_f - * functions. + * Defines default @ref rpn_if_param_s.setres_f and @ref rpn_if_param_s.getarg_f + * functions and flags to select them (see @ref ifs_if_default_posflag and + * @ref ifs_if_default_resflag ). + * + * The @ref rpn_if_default_params function constructs suitable + * @ref rpn_if_param_t to instanciate an @ref rpn_if_t with + * @ref rpn_if_new function. */ -#include "config.h" -#include "rpn_if.h" - /**@weakgroup ifs_if_default_posflag Default IF position flags * @ingroup ifs_if_default * @{ */ @@ -65,6 +69,7 @@ typedef struct rpn_if_default_data_s rpn_if_default_data_t; /**@brief Stores default IF data * * Stores flags and size limit + * @ingroup ifs_if_default */ struct rpn_if_default_data_s { @@ -77,7 +82,8 @@ struct rpn_if_default_data_s * @note If NULL no limit * - For @ref RPN_IF_POSITION_LINEAR size_lim is a single size_t * - For @ref RPN_IF_POSITION_XY size_lim is two size_t (height and width) - * - For @ref RPN_IF_POSITION_XDIM *size_lim is the size of size_lim + * - For @ref RPN_IF_POSITION_XDIM the first element (*size_lim) is the + * size of the size_lim array */ size_t *size_lim; @@ -101,10 +107,11 @@ struct rpn_if_default_data_s * (@ref ifs_if_default_resflag ) * @param lim Depends on pos_flag parameter ( * see @ref rpn_if_default_data_s::size_lim ) - * @param val Depends on res_flag parameter ( + * @param res_const Depends on res_flag parameter ( * see @ref rpn_if_default_data_s::const_val ) + * @param rpn_stack_sz The size of the stack for expressions * @returns A new @ref rpn_if_param_t or NULL on error - * @todo Implementation/testing + * @ingroup ifs_if_default */ rpn_if_param_t* rpn_if_default_params(short pos_flag, short res_flag, const size_t *lim, const rpn_value_t *res_const, @@ -113,7 +120,7 @@ rpn_if_param_t* rpn_if_default_params(short pos_flag, short res_flag, /** Fetch size limit and const values array sizes given flag values * @param pos_flag (@ref ifs_if_default_posflag) * @param res_flag (@ref ifs_if_default_resflag) - * @param short[2] size limit array size and constant values array size + * @param sizes size limit array size and constant values array size * @return 0 or -1 if a flag is not valid * @warning returns 1 for size limit when XDIM position, but actually the * limit is given by the 1st number in the limit (example : [2,640,480], @@ -122,16 +129,37 @@ rpn_if_param_t* rpn_if_default_params(short pos_flag, short res_flag, */ int rpn_if_sizes_from_flag(short pos_flag, short res_flag, short sizes[2]); -/**@brief Default argf function ( see @ref rpn_if_param_s.arg_f ) */ +/**@brief Default argf function ( see @ref rpn_if_param_s.getarg_f ) + * + * This function handle internal rif modification to set next arguments. + * It will call specialized function depending on + * @ref rpn_if_default_data_s.pos_flag and @ref rpn_if_default_data_s.res_flag + * @note The position is the first set of arguments and can be use to + * look for the other one + * + * @param rif Pointer on expressions + * @param pos The position + * @return 0 or -1 on error + */ int rpn_if_getarg_default(rpn_if_t *rif, size_t pos); -/**@brief Default result function ( see @ref rpn_if_param_s.res_f ) */ + +/**@brief Default result function ( see @ref rpn_if_param_s.setres_f ) + * + * This function will store the result at given position and + * It will call specialized function depending on + * @ref rpn_if_default_data_s.pos_flag and @ref rpn_if_default_data_s.res_flag + * @param rif Pointer on expressions + * @param pos Will be set to the resulting position + * @return 0 or -1 on error + */ int rpn_if_setres_default(rpn_if_t *rif, size_t *pos); -/**@brief Set the first expression argument from position +/**@brief Set the first expression argument from linear position * @param rif Expressions * @param pos Memory map offset * @param args pointer on expressions arguments - * @note Other arguments are set using the generic @ref rpn_if_argf_default + * @return 0 or -1 on error + * @note Other arguments are set using the generic @ref rpn_if_getarg_default * function */ int rpn_if_argf_linear(rpn_if_t *rif, size_t pos, rpn_value_t *args); @@ -139,7 +167,8 @@ int rpn_if_argf_linear(rpn_if_t *rif, size_t pos, rpn_value_t *args); * @param rif Expressions * @param pos Pointer on resulting position in memory map * @param data Pointer on resulting data - * @note Data from position fecth is done by generic @ref rpn_if_resf_default + * @return 0 or -1 on error + * @note Data from position fecth is done by generic @ref rpn_if_setres_default * function */ int rpn_if_resf_linear(rpn_if_t *rif, size_t *pos, rpn_value_t *data); @@ -148,7 +177,8 @@ int rpn_if_resf_linear(rpn_if_t *rif, size_t *pos, rpn_value_t *data); * @param rif Expressions * @param pos Memory map offset * @param args pointer on expression arguments - * @note Other arguments are set using the generic @ref rpn_if_argf_default + * @return 0 or -1 on error + * @note Other arguments are set using the generic @ref rpn_if_getarg_default * function */ int rpn_if_argf_xy(rpn_if_t *rif, size_t pos, rpn_value_t *args); @@ -156,7 +186,8 @@ int rpn_if_argf_xy(rpn_if_t *rif, size_t pos, rpn_value_t *args); * @param rif Expressions * @param pos Memory map offset pointer * @param data Pointer on resulting data - * @note Data from position fetch is done by generic @ref rpn_if_resf_default + * @return 0 or -1 on error + * @note Data from position fetch is done by generic @ref rpn_if_setres_default * function */ int rpn_if_resf_xy(rpn_if_t *rif, size_t *pos, rpn_value_t *data); @@ -165,7 +196,8 @@ int rpn_if_resf_xy(rpn_if_t *rif, size_t *pos, rpn_value_t *data); * @param rif Expressions * @param pos Memory map offset * @param args Pointer on expression arguments - * @note Other arguments are set using the generic @ref rpn_if_argf_default + * @return 0 or -1 on error + * @note Other arguments are set using the generic @ref rpn_if_getarg_default * function */ int rpn_if_argf_xdim(rpn_if_t *rif, size_t pos, rpn_value_t *args); @@ -173,7 +205,8 @@ int rpn_if_argf_xdim(rpn_if_t *rif, size_t pos, rpn_value_t *args); * @param rif Expressions * @param pos Memory map offset pointer * @param data Pointer on resulting data - * @note Data from position fetch is done by generic @ref rpn_if_resf_default + * @return 0 or -1 on error + * @note Data from position fetch is done by generic @ref rpn_if_setres_default * function */ int rpn_if_resf_xdim(rpn_if_t *rif, size_t *pos, rpn_value_t *data); diff --git a/rpn_ifs.h b/rpn_ifs.h index c1fb270..997a68a 100644 --- a/rpn_ifs.h +++ b/rpn_ifs.h @@ -26,6 +26,11 @@ #include "rpn_jit.h" #include "rpn_if.h" +/**@file rpn_ifs.h + * @brief IFS header + * @ingroup ifs + */ + /**@defgroup ifs Iterated function system * @brief IFS implementation with RPN expressions * @@ -130,6 +135,7 @@ int rpn_ifs_weight_update(rpn_ifs_t *rifs); rpn_expr_t **rpn_ifs_flat_rpn(rpn_ifs_t *rifs); /**@brief Randomly choose an IF and make a step updating ifs current posisition + * @param rifs The IF system * @return -1 on error else 0 */ int rpn_ifs_step(rpn_ifs_t *rifs); diff --git a/rpn_jit.h b/rpn_jit.h index 848e968..712c880 100644 --- a/rpn_jit.h +++ b/rpn_jit.h @@ -148,19 +148,20 @@ int rpn_expr_init(rpn_expr_t* expr, const unsigned char stack_sz, /**@brief Reinit an existing @ref rpn_expr_s avoiding mmap and malloc * for executable memory map and for stack - * @param expr + * @param expr Pointer on the expression + * @return 0 or -1 on error */ int rpn_expr_reinit(rpn_expr_t* expr); /**@brief Recompile an existing, allready initialized, expression - * @param rpn_expr_t* The expression - * @param const char * The code to compile + * @param expr The expression + * @param code The code to compile * @return 0 if no error else -1 */ int rpn_expr_recompile(rpn_expr_t *expr, const char *code); /**@brief Takes into account modifications in token representation - * @param rpn_expr_t* + * @param expr The expression with updated tokens * @return 0 if no error else -1 */ int rpn_expr_tokens_updated(rpn_expr_t* expr); @@ -179,10 +180,11 @@ int rpn_expr_compile(rpn_expr_t *expr, const char *code); * @param tokens Tokenized form * @param long_op If true long operation are used, else 1 chr op are used * @return 0 if no error else -1 and @ref rpn_expr_s::err_reason is set - * @note The @ref rpn_tokenized_s::tokens attribute is "captured" by the + * + * @note The @ref rpn_tokenized_s.tokens attribute is "captured" by the * @ref rpn_expr_s structure and will be deallocated when @ref rpn_expr_close * is called. It is not encouraged to keep a reference on this attribute after - * @ref rpn_expr_start_untokenize call (but pointed @ref rpn_tokenized_t + * @ref rpn_expr_untokenize call (but pointed @ref rpn_tokenized_t * can be reused) * @ingroup rpn */ @@ -221,7 +223,6 @@ unsigned long rpn_expr_eval(rpn_expr_t *expr, unsigned long *args); /**@brief Free ressources handled by given @ref rpn_expr_s * @param expr Pointer on rpn_expr_t - * @param expr Pointer on @ref rpn_expr_s * @ingroup rpn */ void rpn_expr_close(rpn_expr_t* expr); @@ -269,7 +270,7 @@ int _rpn_expr_init_map(rpn_expr_t* expr); int _rpn_expr_end_map(rpn_expr_t *expr); /**@brief Reset the memory map, filling it with zeroes and reseting permissions - * @param rpn_expr_t* + * @param expr Pointer on rpn_expr_t * @return 0 if no error else -1 */ int _rpn_expr_reset_map(rpn_expr_t *expr); diff --git a/rpn_lib.h b/rpn_lib.h index fdba564..7e097cb 100644 --- a/rpn_lib.h +++ b/rpn_lib.h @@ -50,7 +50,9 @@ #define CODE_SZ(NAME) NAME ## _sz /**@brief macro to declare a code part and associated size */ -#define CODE_PART(NAME) const extern void* NAME; extern const unsigned long NAME ## _sz +#define CODE_PART(NAME) const extern void* NAME; \ +/**@brief Cord part size */\ +extern const unsigned long NAME ## _sz /**@brief Define the type of value manipulated by RPN expressions * @@ -58,7 +60,9 @@ * @todo use it */ typedef unsigned long int rpn_value_t; +/**@brief Small alias for PyLong_FromUnsignedLong */ #define PyLong_FromRpnValue_t PyLong_FromUnsignedLong +/**@brief Small alias for PyLong_AsUnsignedLong */ #define PyLong_AsRpnValue_t PyLong_AsUnsignedLong /**@brief Function heading code diff --git a/rpn_mutate.h b/rpn_mutate.h index 0c3ca6e..db0c291 100644 --- a/rpn_mutate.h +++ b/rpn_mutate.h @@ -27,10 +27,16 @@ #include "rpn_parse.h" +/**@file rpn_mutate.h + * @brief Expression mutation headers + */ + +/**@brief Mutation parameters */ typedef struct rpn_mutation_params_s rpn_mutation_params_t; +/**@brief Type of random values used by mutations */ typedef uint16_t rnd_t; - +/** @brief Mutation parameters */ struct rpn_mutation_params_s { /**@brief Minimum expression length */ @@ -50,12 +56,15 @@ struct rpn_mutation_params_s * mutating a token*/ float w_mut_elt[3]; - /**@brief For internal use, set by @ref rpn_mutation_init_params + /**@brief For internal use, set by rpn_mutation_init_params * * weight reported by groups on rnd_t integers * - [0..3] -> weights mutation * - [4..6] -> w_add_elt * - [7..9] -> w_mut_elt + * + * @note Weights are stored a way allowing fast random choice. + * They are kind of ascending threshold until @ref rnd_t max value. */ rnd_t _weights[10]; }; @@ -63,42 +72,85 @@ struct rpn_mutation_params_s /**@brief Initialize mutation parameters * * pre-process integers threshold by group - * @param rpn_mutation_params_t* + * @param params * @return 0 if no error else -1 and set ERRNO (EINVAL) */ int rpn_mutation_init_params(rpn_mutation_params_t *params); -/**@brief Mutate a tokenized rpn expression */ +/**@brief Mutate a tokenized rpn expression + * @param toks The tokenized expression + * @param params The mutation parameters + * @return 0 or -1 on error */ int rpn_mutation(rpn_tokenized_t *toks, rpn_mutation_params_t *params); + +/**@brief Mutate an expression by adding a token + * @param toks The tokenized expression + * @param params The mutation parameters + * @return 0 or -1 on error */ int rpn_mutation_add(rpn_tokenized_t *toks, rpn_mutation_params_t *params); +/**@brief Mutate an expression by removing a token + * @param toks The tokenized expression + * @param params The mutation parameters + * @return 0 or -1 on error */ int rpn_mutation_del(rpn_tokenized_t *toks, rpn_mutation_params_t *params); +/**@brief Mutate an expression by changing a token + * @param toks The tokenized expression + * @param params The mutation parameters + * @return 0 or -1 on error */ int rpn_mutation_mut(rpn_tokenized_t *toks, rpn_mutation_params_t *params); +/**@brief Mutate an expression by changing a token value (not type) + * @param toks The tokenized expression + * @param params The mutation parameters + * @return 0 or -1 on error */ int rpn_mutation_mut_soft(rpn_tokenized_t *toks, rpn_mutation_params_t *params); -/**@brief Change the "value" of a token randomly not it's type */ +/**@brief Change the "value" of a token randomly not it's type + * @param tok Point on the token to mutate + * @param toks The tokenized expression the token tok belongs to + * @param params The mutation parameters + * @return 0 or -1 on error */ int rpn_mutation_random_token(rpn_token_t *tok, rpn_tokenized_t *toks, rpn_mutation_params_t *params); -/**@breif Choose a random token type - * @return -1 on error +/**@brief Choose a random token type + * @param type Point on result + * @param weights The weight of each types for the choice + * @note Weights comes from @ref rpn_mutation_params_s._weights and are + * processed in a form allowing a fast random choice. + * @return 0 or -1 on error */ int rpn_random_token_type(rpn_token_type_t *type, rnd_t *weights); -/**@param rnd_t* Is set to a random value +/**@brief Generate a random value + * @param rand Point on result * @return -1 on error else 0 */ int rpn_getrandom(rnd_t *rand); -/**@param size_t Maximum value - * @param size_t* Will be set to a value between [..max[ +/**@brief Generate a random number between 0 and max (max excluded) + * @param max Maximum value + * @param res Will be set to a value between [..max[ * @return -1 on error else 0 */ int rpn_rand_limit(size_t max, size_t *res); -/**@briref Given a size return an element with regards to given weights */ +/**@brief Given a size return an random element with regards to given weights + * @param sz The given size + * @param weights Weights coming from @ref rpn_mutation_params_s._weights + * @param res Points on result + * @return 0 or -1 on error */ int _rpn_random_choice(size_t sz, rnd_t *weights, size_t *res); + +/**@brief Given a size and a (random) value, returns an element with regards + * to given weights + * @param sz The given size + * @param weights Weights coming from @ref rpn_mutation_params_s._weights + * @param rand A (random) value + * @param res Points on result */ void __rpn_random_choice(size_t sz, rnd_t *weights, rnd_t rand, size_t *res); -// Debugging function +/**@brief Debugging function that dump mutation params in a human readable format + * @param fd The file descriptor on wich we should print parameters + * @param params The mutation parameters to dump */ void _print_params(int fd, rpn_mutation_params_t *params); #endif diff --git a/rpn_parse.h b/rpn_parse.h index ad5b1a8..2c1b871 100644 --- a/rpn_parse.h +++ b/rpn_parse.h @@ -37,7 +37,7 @@ * @brief Parsing an expression into a @ref rpn_tokenized_t * * The tokenized form ( see @ref rpn_tokenized_t ) of an expression is usefull - * for @ref mutation. + * for mutations (see @ref rpn_mutate.h ). * * The tokenizing process is done in a way allowing compilation process to * fetch tokens while parsing the expression (see @ref rpn_tok). @@ -164,6 +164,8 @@ struct rpn_tokenizer_s * Stores operation identification informations * @ingroup rpn_tokenize */ extern const rpn_op_t rpn_ops[]; + +/**@brief The count of operand (the size of @ref rpn_ops array) */ extern const size_t RPN_OP_SZ; @@ -223,7 +225,7 @@ char* rpn_tokenized_expr(rpn_tokenized_t *tokens, char long_op); const rpn_op_t* rpn_match_token(const char* token); /**@brief Returns NULL or pointer on corresponding operation infos - * @param unsigned char opcode (index in @ref rpn_ops ) + * @param opcode (index in @ref rpn_ops ) * @return NULL or operation informations */ const rpn_op_t* rpn_op_from_opcode(unsigned char opcode); @@ -244,13 +246,19 @@ int rpn_match_token_i(const char* token); */ int rpn_match_number(const char* token, unsigned long *result); -/**@todo doc */ +/**@brief Stores a token string representation in given buffer + * @param token The token to represent + * @param dst The destination buffer for the string + * @param sz The biffer size + * @return Same as snprintf (the number of chr stored or negative value on error + */ int rpn_token_snprintf(rpn_token_t *token, char *dst, size_t sz); /**@brief Get operations list size * @return number of operations in @ref rpn_ops */ size_t rpn_op_sz(); +/**@brief Macro version of @ref rpn_op_sz() */ #define RPN_OPS_SZ (sizeof(rpn_ops)/sizeof(rpn_op_t)) /**@page rpn_lang RPN expression syntax @@ -287,7 +295,7 @@ size_t rpn_op_sz(); * Each valid operations are declared in @ref rpn_ops variable (see * @ref rpn_parse.c for details). * - * The @ref python_module expose a function pyrpn.get_ops() ( @see pyrpn_ops ) + * The @ref pymod_pyrpn expose a function pyrpn.get_ops() ( @see pyrpn_ops ) * returning a dict with long operations as key and short as value. * \subsubsection rpn_lan_op_internal Internal mechanism * Operations are done using a loopstack : operands are poped from stack, and