Comment & doxygen documentation enhancement

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

config.h

@@ -19,12 +19,21 @@
 #ifndef __RPN_CONFIG__
 #define __RPN_CONFIG__
 
-#define _GNU_SOURCE
-
+/**@file config.h
+ * @brief Global definition for all C files
+ */
 
-#define PYRPN_doc_meth(NAME, header, docstring) PyDoc_STRVAR(NAME ## _doc,\
-		header "\n--\n\n" docstring);
+/**@brief The programms is under GPL */
+#define _GNU_SOURCE
 
+/**@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)}

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;

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

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*/
+

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);
-int rpnif_expr_ass_item(PyObject *self, Py_ssize_t idx, PyObject* elt);
+/**@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);
 
 

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,

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);
 

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");

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);
 

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"},

python_rpntoken.h

@@ -26,56 +26,186 @@
 #include <Python.h>
 #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
  *
  */
 
+/**@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;
-extern PyModuleDef rpntokens_module;
 
+
+/**@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

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 !
  */

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);

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);

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);

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

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

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