Commenting libs/cturmit.h

libs/cturmit.c

@@ -277,18 +277,12 @@ PyObject* CTurmit_call(PyObject *func, PyObject *args, PyObject *kwds)
 				err_msg);
 			Py_RETURN_NONE;
 		}
-                Py_DECREF(arg);
+		Py_DECREF(arg);
 	}
 	res = turmit_exec(self->turmit, exec_args);
 	return PyLong_FromUnsignedLongLong(res);
 }
 
-Py_ssize_t
-CTurmit_len(CTurmit *self)
-{
-	return self->len;
-}
-
 PyObject* CTurmit__push(CTurmit* self, PyObject *args)
 {
 	char err_msg[128];

libs/cturmit.h

@@ -3,49 +3,33 @@
 
 #include "turmit.h"
 
-/**
- * @todo search for decref and memory leaks :/
- */
-
-typedef struct
-{
-	PyObject VAR_HEAD;
-	
-	Py_ssize_t len;
-	turmit_t *turmit;
-} CTurmit;
+/** @brief Python module containing CTurmit python class */
 
 static PyModuleDef cturmitmodule = {
 	PyModuleDef_HEAD_INIT,
 	"cturmit",
-	"Module that implements turmits in C",
+	"Module implementing turmits in C",
 	-1,
 	NULL, NULL, NULL, NULL, NULL
-};
+}; /*<! Module description */
 
+/*
+	class CTurmit definitions
+*/
+
+typedef struct
+{
+	PyObject VAR_HEAD;
+	
+	turmit_t *turmit; /*<! Ref to a turmit_t from libs/turmit.h */
+} CTurmit; /*<! CTurmit struct */
 
 static PyMemberDef CTurmit_members[] = {
-	{"len", T_PYSSIZET, offsetof(CTurmit, len), 0,
-		"Expression len"},
-	/*
-	   {"heap_sz", T_PYSSIZET, offsetof(CTurmit, heap_sz), 0,
-	   "Item heap counter"},
-	 */
 	{NULL}  /* Sentinel */
-};
+}; /*<! CTurmit member attribute description */
 
-/*
-	Magic methods
-*/
-Py_ssize_t CTurmit_len(CTurmit*);
 
-static PyMappingMethods CTurmit_asmapping[] = {{
-	(void*)CTurmit_len,
-}};
-
-/*
-	Other methods
-*/
+/* Other methods */
 #define TURMIT_PYOP(NAME) PyObject* CTurmit_op_##NAME(CTurmit* self) {\
 	turmit_op_##NAME(self->turmit);\
 	Py_RETURN_NONE;\
@@ -53,8 +37,22 @@ static PyMappingMethods CTurmit_asmapping[] = {{
 #define TURMIT_PYOPDEF(NAME) {#NAME, (PyCFunction)CTurmit_op_##NAME, \
 	METH_NOARGS, NULL}
 
+/** @brief Push a python integer on the CTurmit stack
+ * @param self the CTurmit instance
+ * @param PyObject* list of *args arguments. Should contain a single integer
+ * argument to be pushed on the stack
+ * @return Python None
+ * @throws TypeError if bad arguments
+ */
 PyObject* CTurmit__push(CTurmit* self, PyObject *args);
+/**@brief Pop a python integer from the CTurmit stack
+ * @return a python integer returned from PyLong_FromUnsignedLongLong()
+ */
 PyObject* CTurmit__pop(CTurmit* self);
+/* Adding method to call turmit_t operations on the stack
+ * @param self CTurmit* (see TURMIT_PYOP macro) the method takes no args
+ * except self
+ */
 TURMIT_PYOP(mem_sz)
 TURMIT_PYOP(add)
 TURMIT_PYOP(sub)
@@ -94,10 +92,28 @@ static PyMethodDef CTurmit_methods[] = {
 	TURMIT_PYOPDEF(jz),
 	TURMIT_PYOPDEF(jcmp),
 	{NULL}  /* Sentinel */
-};
+}; /*<! Static CTurmit method mapping */
+
+/*
+	Getter & setter definition
+
+	Note : no setter, this methods are implemented for read only access
+	to some @ref turmit_t attributes
+*/
 
+/**@brief Returns current value on the top of the stack
+ * @note mapped as "shead" attribute
+ * @retrun a python int
+ */
 PyObject* CTurmit_get_shead(CTurmit *self, void *ref);
+/**@brief Returns current position of the stack head
+ * @note mapped as "_cur" attribute
+ * @retrun a python int
+ */
 PyObject* CTurmit_get__cur(CTurmit *self, void *ref);
+/**@brief Returns a python representation of the stack
+ *@return a python list containing python int
+ */
 PyObject* CTurmit_get__stack(CTurmit *self, void *ref);
 
 static struct PyGetSetDef CTurmit_getset[] = {
@@ -105,14 +121,27 @@ static struct PyGetSetDef CTurmit_getset[] = {
 	{"_cur", (getter)CTurmit_get__cur, NULL, NULL, NULL},
 	{"_stack", (getter)CTurmit_get__stack, NULL, NULL, NULL},
 	{NULL}  /* Sentinel */
-};
-
+};/*<! Getter mapping */
+
+/**@brief Utility method that handle CTurmit instanciation copying an existing
+ * CTurmit instance
+ * @param self Python self CTurmit, the CTurmit to copy
+ * @param t the destination CTurmit
+ * @return 0 if no error else -1
+ * @todo set error to throw python exception if error
+ */
 static int _CTurmit_copy_init(CTurmit *self, CTurmit *t);
 
+/**@brief Python CTurmit.__new__() method
+ * @param type Python type
+ * @param args Python *args positional args list
+ * @param kwds Python **kwargs named args dict
+ * @return a CTurmit with memory allocated for the instance
+ */
 static PyObject *
 CTurmit_new(PyTypeObject *type, PyObject *args, PyObject *kwds);
 
-/**@brief CTurmit __init__ function
+/**@brief CTurmit.__init__(self, stack_size=8, max_int=0x10000, prog="", turmit=None) method
  * @param CTurmit* self
  * @param PyObject* can contain an interger representing stack size
  * @param Pyobject* contains kwargs. Can be : stack_size, max_int, prog
@@ -120,14 +149,21 @@ CTurmit_new(PyTypeObject *type, PyObject *args, PyObject *kwds);
 static int
 CTurmit_init(CTurmit *self, PyObject *args, PyObject *kwds);
 
+/**@brief CTurmit.__del__(self) method
+ * @param self The CTurmit instance
+ */
 void
 CTurmit_dealloc(CTurmit *self);
 
+/**@brief CTurmit.__call__(self, x, y, r, g, b) method
+ * @param args python positional arguments list
+ * @param kwds python named arguments dict
+ */
 PyObject* CTurmit_call(PyObject *func, PyObject *args, PyObject *kwds);
 
 static PyTypeObject CTurmitType = {
 	PyVarObject_HEAD_INIT(NULL, 0)
-		"cturmit.CTurmit",			/* tp_name */
+	"cturmit.CTurmit",				/* tp_name */
 	sizeof(CTurmit),				/* tp_basicsize */
 	0,						/* tp_itemsize */
 	(destructor)CTurmit_dealloc,			/* tp_dealloc */
@@ -138,7 +174,7 @@ static PyTypeObject CTurmitType = {
 	0,						/* tp_repr */
 	0,						/* tp_as_number */
 	0,						/* tp_as_sequence */
-	CTurmit_asmapping,				/* tp_as_mapping */
+	0,						/* tp_as_mapping */
 	0,						/* tp_hash  */
 	CTurmit_call,					/* tp_call */
 	0,						/* tp_str */
@@ -164,6 +200,6 @@ static PyTypeObject CTurmitType = {
 	(initproc)CTurmit_init,				/* tp_init */
 	0,						/* tp_alloc */
 	CTurmit_new,					/* tp_new */
-};
+}; /*<! CTurmit object mapping */