update documentation

2 files changed, 103 insertions, 9 deletions

diff --git a/pcilib/py.h b/pcilib/py.h
index 549eddf..62ce7db 100644
--- a/pcilib/py.h
+++ b/pcilib/py.h
@@ -125,23 +125,55 @@ int pcilib_py_eval_func(pcilib_t *ctx, const char *script, const char *func, pci
  *  @return 		- NULL or cloned pcilib_py_t content pointer on success
  */
 pcilib_py_t* pcilib_init_py_ctx(pcilib_py_t* in, int *err);
+
+/**
+ * @brief pcilib_t independent variant  pcilib_free_py
+ * @param ctx_py[in,out] - pcilib_py_t context
+ */
+void pcilib_free_py_ctx(pcilib_py_t *ctx_py);
+
+/** pcilib_t independent variant of pcilib_py_eval_func()
+ * @param ctx_py[in,out] - pcilib_py_t context
+ * @param name[in] - script name
+ * @param name[in] - function name
+ * @param pyval[in] - input value (will be decref in this fucntion)
+ * @param err[out] - error
+ * @return value returned by python function
+ */
 pcilib_py_object* pcilib_py_ctx_eval_func(pcilib_py_t *ctx_py,
-                                          const char *script_name,
+                                          const char *name,
                                           const char *func_name, 
                                           pcilib_py_object *pyval, 
                                           int *err);
-int pcilib_py_ctx_add_script_dir(pcilib_py_t *ctx_py, const char *dir);
-void pcilib_free_py_ctx(pcilib_py_t *ctx_py);
-int pcilib_py_ctx_load_script(pcilib_py_t *ctx_py, const char *script_name);
+
+/**
+ * @brief pcilib_t independent variant of pcilib_py_add_script_dir
+ * @param ctx_py[in,out] - pcilib_py_t context
+ * @param[in] location 	- NULL or path to additional scripts
+ * @return
+ */
+int pcilib_py_ctx_add_script_dir(pcilib_py_t *ctx_py, const char *location);
+
+/**
+ * @brief pcilib_t independent variant of pcilib_py_load_script
+ * @param ctx_py[in,out] - pcilib_py_t context
+ * @param[in] name	- script name, the passed variable is referenced and, hence, should have static duration
+ * @return
+ */
+int pcilib_py_ctx_load_script(pcilib_py_t *ctx_py, const char *name);
+
+/**
+ * @brief Returns information about scripts aviable in model
+ * @param ctx_py[in,out] - pcilib_py_t context
+ * @return List with information about scripts
+ */
 pcilib_py_object *pcilib_py_ctx_get_scripts_info(pcilib_py_t *ctx_py);
 
-/*!
- * \brief Wrap for PyDict_SetItem, with decrease reference counting after set.
+/** Wrap for PyDict_SetItem, with decrease reference counting after set.
  */
 void pcilib_pydict_set_item(pcilib_py_object* dict, pcilib_py_object* name, pcilib_py_object* value);
 
-/*!
- * \brief Wrap for PyList_Append, with decrease reference counting after append.
+/** Wrap for PyList_Append, with decrease reference counting after append.
  */
 void pcilib_pylist_append(pcilib_py_object* list, pcilib_py_object* value);
 #ifdef __cplusplus
diff --git a/pywrap/pcipywrap.h b/pywrap/pcipywrap.h
index cfb5651..fa7e4f4 100644
--- a/pywrap/pcipywrap.h
+++ b/pywrap/pcipywrap.h
@@ -73,18 +73,55 @@ PyObject* Pcipywrap_get_property(Pcipywrap *self, const char *prop);
  * \return 1, serialized to PyObject or NULL with exeption text, if failed.
  */
 PyObject* Pcipywrap_set_property(Pcipywrap *self, PyObject* val, const char *prop);
+
+
+/*!
+ * \brief Wrap for pcilib_get_register_list function.
+ * \param bank [in]	bank - if set, only register within the specified bank will be returned
+ * \return list of registers, serialized to Python object
+ */
 PyObject* Pcipywrap_get_registers_list(Pcipywrap *self, const char *bank);
+
+/*!
+ * \brief Returns the information about the specified register. Wrap for pcilib_get_register_info
+ * \param[in] reg the name of the register
+ * \param[in] bank indicates the bank where to look for register, autodetected if NULL is passed
+ * \return information about the specified register, serialized to Python object
+ */
 PyObject* Pcipywrap_get_register_info(Pcipywrap *self, const char* reg,const char *bank);
+
+/*!
+ * \brief Returns the list of properties available under the specified path. Wrap for pcilib_get_property_list
+ * \param[in] branch path or NULL to return the top-level properties
+ * \return the list of the properties, serialized to Python object
+ */
 PyObject* Pcipywrap_get_property_list(Pcipywrap *self, const char* branch);
 
+/*!
+ * \brief Reads data from DMA until timeout is hit, a full DMA packet is read, or the specified number of bytes are read.
+ * Wrap for pcilib_read_dma.
+ * \param dma ID of DMA engine
+ * \param size specifies how many bytes should be read
+ * \return DMA data, serialierd to Python bytearray
+ * \warning This function has not been tested.
+ * \todo Test this fucntion
+ */
 PyObject* Pcipywrap_read_dma(Pcipywrap *self, unsigned char dma, size_t size);
 
+/*!
+ * \brief Wrap for pcilib_lock_global
+ * \return 1, serialized to PyObject or NULL with exeption text, if failed.
+ */
 PyObject* Pcipywrap_lock_global(Pcipywrap *self);
+
+/*!
+ * \brief Wrap for pcilib_unlock_global
+ */
 void Pcipywrap_unlock_global(Pcipywrap *self);
 
 /*!
  * \brief Wrap for pcilib_lock
- * \param lock_id lock identificator
+ * \param[in] lock_id lock identificator
  * \warning This function should be called only under Python standart threading lock.
  * Otherwise it will stuck with more than 1 threads. See /xml/test/test_prop_mt.py
  * for example.
@@ -92,10 +129,35 @@ void Pcipywrap_unlock_global(Pcipywrap *self);
  */
 PyObject* Pcipywrap_lock(Pcipywrap *self, const char *lock_id);
 
+/*!
+ * \brief This function will try to take a lock for the mutex pointed by
+ * lockfunction to acquire a lock, but that returns immediatly if the lock can't be
+ * acquired on first try. Wrap for pcilib_try_lock.
+ * \param[in] lock_id lock id
+ * \return 1, serialized to PyObject or NULL with exeption text, if failed.
+ */
 PyObject* Pcipywrap_try_lock(Pcipywrap *self, const char *lock_id);
+
+/*!
+ * \brief This function unlocks the lock with specified id. Wrap for pcilib_unlock.
+ * \param[in] lock_id lock id
+ * \return 1, serialized to PyObject or NULL with exeption text, if failed.
+ */
 PyObject* Pcipywrap_unlock(Pcipywrap *self, const char *lock_id);
 
+/*!
+ * \brief Returns list with information about aviable scripts
+ * \return list with information about scripts, aviable in model
+ */
 PyObject* Pcipywrap_get_scripts_list(Pcipywrap *self);
+
+/*!
+ * \brief Runs script with specified name
+ * \param script_name script name (with extension); name could be found by
+ * Pcipywrap_get_scripts_list fucntion
+ * \param[in] value input value
+ * \return value returned by script
+ */
 PyObject* Pcipywrap_run_script(Pcipywrap *self, const char* script_name, PyObject* value);
 
 #endif /* PCIPYWRAP_H */