Write doxygen documentation

src/cooling_wrapper.h

@@ -3,8 +3,30 @@
 
 #include "pyswiftsim_tools.h"
 
+/**
+ * @brief Initialize the cooling
+ *
+ * args is expecting pyswiftsim classes in the following order:
+ * SwiftParams, UnitSystem and PhysConst. 
+ *
+ * @param self calling object
+ * @param args arguments
+ * @return CoolingFunctionData
+ */
 PyObject* pycooling_init(PyObject* self, PyObject* args);
 
+/**
+ * @brief Compute cooling rate
+ *
+ * args is expecting pyswiftsim classes in the following order: 
+ * PhysConst, UnitSystem and CoolingFunctionData.
+ * Then two numpy arrays (density and specific energy) and an optional
+ * float for the time step
+ *
+ * @param self calling object
+ * @param args arguments
+ * @return cooling rate
+ */
 PyArrayObject* pycooling_rate(PyObject* self, PyObject* args);
 
 #endif // __PYSWIFTSIM_COOLING_H__

src/parser_wrapper.h

@@ -3,6 +3,15 @@
 
 #include <Python.h>
 
+/**
+ * @brief Read swift parameters
+ *
+ * args is expecting a string.
+ *
+ * @param self calling object
+ * @param args arguments
+ * @return SwiftParams
+ */
 PyObject* pyparser_read_file(PyObject *self, PyObject *args);
 
 

src/part_wrapper.h

@@ -4,6 +4,15 @@
 #include <Python.h>
 #include <part.h>
 
+/**
+ * @brief Test function for the struct
+ *
+ * args is expecting no argument. 
+ *
+ * @param self calling object
+ * @param args arguments
+ * @return Part
+ */
 PyObject* pypart_test_struct(PyObject *self, PyObject *args);
 
 #endif // __PYSWIFTSIM_PART_H__

src/pyswiftsim_tools.c

@@ -71,12 +71,15 @@ PyObject* pytools_return(void *p, int class)
   char module_name[STRING_SIZE] = "pyswiftsim.structure";
   char *class_pyname;
 
+  /* check class */
   if (class >= class_count)
     pyerror("Class %i does not exists", class);
 
+  /* get class information */
   nber_bytes = class_size[class];
   class_pyname = class_name[class];
 
+  /* import python class */
   python_class = pytools_import(module_name, class_pyname);
 
   if (python_class == NULL)
@@ -104,13 +107,15 @@ PyObject* pytools_return(void *p, int class)
 
 char* pytools_get_type_name(PyObject *obj)
 {
+  /* get object type */
   PyObject *type = PyObject_Type(obj);
   if (type == NULL)
     {
       Py_DECREF(type);
       pyerror("Unable to get type");
     }
-  
+
+  /* get object name */
   PyObject* recv = PyObject_Str(type);
   Py_DECREF(type);
 
@@ -119,7 +124,8 @@ char* pytools_get_type_name(PyObject *obj)
       Py_DECREF(recv);
       pyerror("Unable to get string representation");
     }
-  
+
+  /* transform to C */
   size_t size;
   char *name = PyUnicode_AsUTF8AndSize(recv, size);
   Py_DECREF(recv);
@@ -138,13 +144,17 @@ char* pytools_construct(PyObject* obj, int class)
   char *module_name = "pyswiftsim.structure";
   char *class_pyname;
 
+  /* check python class */
   if (class >= class_count)
     pyerror("Class %i does not exists", class);
 
+  /* get class information */
   class_pyname = class_name[class];
 
+  /* import class */
   PyObject *pyclass = pytools_import(module_name, class_pyname);
 
+  /* check if classes correspond */
   int test = !PyObject_IsInstance(obj, pyclass);
   Py_DECREF(pyclass);
   if (test)
@@ -155,7 +165,8 @@ char* pytools_construct(PyObject* obj, int class)
       pyerror("Expecting class %s, received %s", class_pyname, recv);
     }
 
-  
+
+  /* copy python class' data to C */
   PyObject* data = PyObject_GetAttrString(obj, "data");
 
   if (data == NULL)
@@ -170,18 +181,22 @@ char* pytools_construct(PyObject* obj, int class)
 
 int pytools_check_array(PyArrayObject *obj, int dim, int type)
 {
+  /* ensure to have numpy arrays */
   IMPORT_ARRAY();
-  
+
+  /* check if array */
   if (!PyArray_Check(obj))
     {
       pyerror("Expecting a numpy array");
     }
-  
+
+  /* check if required dim */
   if (PyArray_NDIM(obj) != dim)
     {
       pyerror("Array should be a %i dimensional object", dim);
     }
 
+  /* check data type */
   if (PyArray_TYPE(obj) != type)
     {
       pyerror("Wrong array type");

src/pyswiftsim_tools.h

@@ -29,6 +29,7 @@
     return FAIL;						\
   })
 
+/* debugging function */
 #define pydebug(s, ...)						\
   ({								\
     PyErr_Print();						\
@@ -36,7 +37,8 @@
 	    __FUNCTION__, __LINE__, ##__VA_ARGS__);		\
   })
 
-enum class {
+/* Enum swift classes */
+enum swift_class {
   class_unit_system,
   class_part,
   class_swift_params,
@@ -45,21 +47,61 @@ enum class {
   class_count /* should always be last! */
 };
 
+/* size of each structure in enum swift_class */
 extern const size_t class_size[];
+/* name of each Python class representing a swift class */
 extern const char *class_name[];
 
+/* error code in pyswiftsim */
 enum error_code {
   FAIL = 0, // ensure NULL == FAIL
   SUCCESS,
 };
 
+
+/**
+ * @brief Construct a python object from a C struct
+ *
+ * @param p pointer to the C struct
+ * @param class #swift_class of the pointer
+ * @return PyObject of the required class
+ */
 PyObject* pytools_return(void* p, int class);
 
+/**
+ * @brief Construct a C struct from a python object
+ *
+ * @param obj pointer to the python object
+ * @param class #swift_class of the pointer
+ * @return pointer to the required struct
+ */
 char* pytools_construct(PyObject* obj, int class);
 
+/**
+ * @brief Import a python library/function
+ *
+ * @param module Module name
+ * @param object_name object to import from module
+ * @return (PyObject) imported object
+ */
 PyObject* pytools_import(char* module, char* object_name);
 
+/**
+ * @brief get type name in C
+ *
+ * @param obj PyObject from which to get the name0
+ * @return type name
+ */
 char* pytools_get_type_name(PyObject *obj);
 
+/**
+ * @brief Check if object is the expected PyArray type
+ *
+ * @param obj PyArray to check
+ * @param dim required dimension
+ * @param int required type
+ * @return #error_code result of the test
+ */
 int pytools_check_array(PyArrayObject *obj, int dim, int type);
+
 #endif // __PYSWIFTSIM_TOOLS_H__

src/units_wrapper.h

@@ -3,8 +3,26 @@
 
 #include <Python.h>
 
+/**
+ * @brief Test function for the struct
+ *
+ * args is expecting no argument. 
+ *
+ * @param self calling object
+ * @param args arguments
+ * @return UnitSystem
+ */
 PyObject* pyunit_system_test_struct(PyObject *self, PyObject *args);
 
+/**
+ * @brief Initialize the unit system
+ *
+ * args is expecting a pyswift SwiftParms object. 
+ *
+ * @param self calling object
+ * @param args arguments
+ * @return UnitSystem
+ */
 PyObject* pyunit_system_init(PyObject *self, PyObject *args);
 
 #endif // __PYSWIFTSIM_UNITS_H__

src/wrapper.c

@@ -54,7 +54,9 @@ PyMODINIT_FUNC PyInit_wrapper(void)
 {
   PyObject *m;
 
+  /* set time for swift */
   clocks_set_cpufreq(0);
+  
   import_array();
   Py_Initialize();
   m = PyModule_Create(&wrapper_cmodule);