call_obj: fix Doxygen comments.

src/modules/call_obj/call_obj_mod.c

@@ -21,6 +21,22 @@
  *
  */
 
+/**
+ * \file
+ * \ingroup call_obj
+ * \brief call_obj :: Core module interface
+ *
+ * - Module: \ref call_obj
+ */
+
+/**
+ * \defgroup call_obj call_obj :: Identify calls using an increasing sequence of integers.
+ *
+ * It starts assigning an integer to a call. Next call gets next free
+ * integer in a ring. When a call finishes its assigned number shall be
+ * freed.
+ */
+
 #include <inttypes.h>
 
 #include "cobj.h"
@@ -43,11 +59,13 @@ static int mod_init(void);
 static void mod_destroy(void);
 
 /**
- * Module parameters
+ * \name Module parameters
+ * @{
  */
-/* Actually, negative or zero values are not allowed. */
-int call_obj_start = 0;
-int call_obj_end = 0;
+int call_obj_start = 0;/**< Start value of counting sequence. Negative values not allowed. */
+int call_obj_end = 0; /**< End value of counting sequence. Negative values not allowed.*/
+
+/**@}*/
 
 /* module commands */
 static cmd_export_t cmds[] = {
@@ -213,6 +231,9 @@ static rpc_export_t rpc_cmds[] = {
 	{0, 0, 0, 0}
 };
 
+/**
+ * \brief Functions and parameters exported by call_obj module.
+ */
 struct module_exports exports = {
 	"call_obj",
 	DEFAULT_DLFLAGS, /* dlopen flags */
@@ -251,13 +272,13 @@ static void mod_destroy(void)
 }
 
 /**
- * Looks for the Call-ID header
+ * \brief Looks for the Call-ID header
  * On error content pointed by s is undefined.
  *
- * @param msg - the sip message
- * @param s  pointer to str where we will store callid.
+ * \param msg - the sip message
+ * \param s  pointer to str where we will store callid.
  *
- * @returns 0 on success
+ * \return 0 on success
  */
 static int get_call_id(struct sip_msg *msg, str *s)
 {
@@ -422,11 +443,11 @@ error:
 }
 
 /**
- * Free an object.
+ * \brief Free an object.
  *
- * /param num_obj number of the object to free.
- * /return 1 on success.
- * /return 0 on error.
+ * \param num_obj number of the object to free.
+ * \return 1 on success.
+ * \return 0 on error.
  */
 static int ki_call_obj_free(sip_msg_t *msg, int num_obj)
 {
@@ -458,7 +479,7 @@ static sr_kemi_t sr_kemi_call_obj_exports[] = {
 /* clang-format on */
 
 /**
- *
+ * Register KEMI functions.
  */
 int mod_register(char *path, int *dlflags, void *p1, void *p2)
 {

src/modules/call_obj/cobj.c

@@ -22,6 +22,14 @@
  */
 
 /**
+ * \file
+ * \ingroup call_obj
+ * \brief call_obj :: Module functionality.
+ *
+ * - Module: \ref call_obj
+ */
+
+/*
  * Functionality of call_obj module.
  */
 
@@ -36,37 +44,42 @@
 #include "cobj.h"
 
 /**
- * Element of the array.
+ * \brief Element of the array.
+ *
  * When assigned equals false other contents are undefined.
  */
 typedef struct {
-	bool assigned;
-	uint64_t timestamp;
-	str callid;
+	bool assigned; /**< Element of the array is assigned. */
+	uint64_t timestamp; /**< Timestamp when element was assigned. */
+	str callid; /**< Call-ID of associated call. */
 } co_object_t;
 
+/**
+ * \brief Data type for shared called_obj data between processes.
+ */
 typedef struct {
-	int start; /* Number of first object. */
-	int end; /* Number of last object (included). */
+	int start; /**< Number of first object. */
+	int end; /**< Number of last object (included). */
 	/**
-	 * Current position of last assigned object.
+	 * \brief Current position of last assigned object.
+	 *
 	 * 0 - no object has been assigned yet.
 	 */
 	int cur;
-	int assigned; /* Number of assigned objects at this moment. */
-	gen_lock_t *lock; /* Lock to protect ring array. */
-	co_object_t *ring; /* Array of call objects. */
+	int assigned; /**< Number of assigned objects at this moment. */
+	gen_lock_t *lock; /**< Lock to protect ring array. */
+	co_object_t *ring; /**< Array of call objects. */
 } co_data_t;
 
 /**
- * Struct containing all call object related data.
+ * \brief Struct containing all call object related data.
  */
 static co_data_t *co_data = NULL;
 
 /**
- * Initialize call object module.
+ * \brief Initialize call object module.
  *
- * /return 0 on success.
+ * \return 0 on success.
  */
 int cobj_init(int start, int end)
 {
@@ -109,7 +122,7 @@ int cobj_init(int start, int end)
 	}
 	LM_DBG("Allocated %lu bytes for the ring\n", array_size);
 
-	/**
+	/*
 	 * Initialize lock.
 	 */
 	co_data->lock = lock_alloc();
@@ -144,7 +157,7 @@ int cobj_init(int start, int end)
 }
 
 /**
- * Close call object module.
+ * \brief Close call object module.
  */
 void cobj_destroy(void)
 {
@@ -174,10 +187,10 @@ void cobj_destroy(void)
 }
 
 /**
- * Get current timestamp in milliseconds.
+ * \brief Get current timestamp in milliseconds.
  *
- * /param ts pointer to timestamp integer.
- * /return 0 on success.
+ * \param ts pointer to timestamp integer.
+ * \return 0 on success.
  */
 int get_timestamp(uint64_t *ts)
 {
@@ -196,9 +209,9 @@ int get_timestamp(uint64_t *ts)
 }
 
 /**
- * Fill an object with data.
+ * \brief Fill an object with data.
  *
- * /return 0 on success.
+ * \return 0 on success.
  */
 static int cobj_fill(co_object_t *obj, uint64_t timestamp, str *callid)
 {
@@ -226,12 +239,12 @@ clean:
 }
 
 /**
- * Get a free object.
+ * \brief Get a free object.
  *
- * /param timestamp assign this timestamp to the object we get.
- * /param callid pointer to callid str.
- * /return -1 if an error happens.
- * /return number of a free object on success.
+ * \param timestamp assign this timestamp to the object we get.
+ * \param callid pointer to callid str.
+ * \return -1 if an error happens.
+ * \return number of a free object on success.
  */
 int cobj_get(uint64_t timestamp, str *callid)
 {
@@ -307,10 +320,10 @@ clean:
 }
 
 /**
- * Free an Object
+ * \brief Free an Object
  *
- * /param num number of object to free
- * /return 0 on success
+ * \param num number of object to free
+ * \return 0 on success
  */
 int cobj_free(int num)
 {
@@ -348,10 +361,10 @@ clean:
 }
 
 /**
- * Fill data in cobj_stats_t structure passed as pointer.
+ * \brief Fill data in cobj_stats_t structure passed as pointer.
  *
- * /param stats pointer to cobj_stats_t structure.
- * /return 0 on success
+ * \param stats pointer to cobj_stats_t structure.
+ * \return 0 on success
  */
 int cobj_stats_get(cobj_stats_t *stats)
 {
@@ -379,7 +392,7 @@ clean:
 }
 
 /**
- * Free all objects at once.
+ * \brief Free all objects at once.
  */
 void cobj_free_all(void)
 {
@@ -402,7 +415,7 @@ void cobj_free_all(void)
 			obj->assigned = false;
 		}
 
-	} // for i
+	} /* for i */
 
 	co_data->cur = 0; /* No object assigned yet. */
 	co_data->assigned = 0; /* No assigned objects at this moment. */
@@ -413,16 +426,16 @@ void cobj_free_all(void)
 }
 
 /**
- * Get all objects which timestamp is less than or equals some value.
+ * \brief Get all objects which timestamp is less than or equals some value.
  *
  * User shall free returned list when not used any more.
  *
- * /param ts timestamp to compare.
- * /param elem returned list. NULL on error of if zero elements.
- * /param limit maximum number of objects to return. 0 means unlimited.
+ * \param ts timestamp to compare.
+ * \param elem returned list. NULL on error of if zero elements.
+ * \param limit maximum number of objects to return. 0 means unlimited.
  *
- * /return number of returned objects on success.
- * /return -1 on error
+ * \return number of returned objects on success.
+ * \return -1 on error
  */
 int cobj_get_timestamp(uint64_t ts, cobj_elem_t **elem, int limit)
 {
@@ -518,9 +531,9 @@ clean:
 }
 
 /**
- * Free an object list.
+ * \brief Free an object list.
  *
- * /param elem pointer to first element in the list.
+ * \param elem pointer to first element in the list.
  */
 void cobj_free_list(cobj_elem_t *elem)
 {

src/modules/call_obj/cobj.h

@@ -22,6 +22,15 @@
  */
 
 /**
+ * \file
+ * \ingroup call_obj
+ * \brief call_obj :: Module functionality
+ *
+ * - See \ref cobj.c
+ * - Module: \ref call_obj
+ */
+
+/*
  * Header for functionality of Call Object module.
  */
 
@@ -33,95 +42,94 @@
 #include "../../core/str.h"
 
 /**
- * Initialize call object module.
+ * \brief Initialize call object module.
  *
- * /return 0 on success.
+ * \return 0 on success.
  */
 int cobj_init(int c_start, int c_end);
 
 /**
- * Close call object module.
+ * \brief Close call object module.
  */
 void cobj_destroy(void);
 
 /**
- * Get a free object.
+ * \brief Get a free object.
  *
- * /param timestamp assign this timestamp to the object we get.
- * /param callid pointer to callid str.
- * /return -1 if an error happens.
- * /return number of a free object on success.
+ * \param timestamp assign this timestamp to the object we get.
+ * \param callid pointer to callid str.
+ * \return -1 if an error happens.
+ * \return number of a free object on success.
  */
 int cobj_get(uint64_t timestamp, str *callid);
 
 /**
- * Free an Object
+ * \brief Free an Object
  *
- * /param num number of object to free
- * /return 0 on success
+ * \param num number of object to free
+ * \return 0 on success
  */
 int cobj_free(int num);
 
 /**
- * Structure to store module statistics.
+ * \brief Structure to store module statistics.
  */
 typedef struct {
-	int start;
-	int end;
-	int assigned;
+	int start; /**< First element in the array. */
+	int end; /**< Last element in the array (included). */
+	int assigned; /**< Number of currently assigned elements. */
 } cobj_stats_t;
 
 /**
- * Fill data in cobj_stats_t structure passed as pointer.
+ * \brief Fill data in cobj_stats_t structure passed as pointer.
  *
- * /param stats pointer to cobj_stats_t structure.
- * /return 0 on success
+ * \param stats pointer to cobj_stats_t structure.
+ * \return 0 on success
  */
 int cobj_stats_get(cobj_stats_t *stats);
 
 /**
- * Free all objects at once.
+ * \brief Free all objects at once.
  */
 void cobj_free_all(void);
 
 /**
- * Element of a returned object list.
+ * \brief Element of a returned object list.
  */
 typedef struct _cobj_elem {
-	int number;
-	uint64_t timestamp;	
-	str callid;
-	/* TODO */
-	struct _cobj_elem *next;
+	int number; /**< Number assigned to the call. */
+	uint64_t timestamp;	/**< Timestamp for the call. */
+	str callid; /**< Call-ID of the call. */
+	struct _cobj_elem *next; /**< Next element in the list. */
 } cobj_elem_t;
 
 /**
- * Free an object list.
+ * \brief Free an object list.
  *
- * /param elem pointer to first element in the list.
+ * \param elem pointer to first element in the list.
  */
 void cobj_free_list(cobj_elem_t *elem);
 
 /**
- * Get current timestamp in milliseconds.
+ * \brief Get current timestamp in milliseconds.
  *
- * /param ts pointer to timestamp integer.
- * /return 0 on success.
+ * \param ts pointer to timestamp integer.
+ * \return 0 on success.
  */
 int get_timestamp(uint64_t *ts);
 
 /**
- * Get all objects which timestamp is less than or equals some value.
+ * \brief Get all objects which timestamp is less than or equals some value.
  *
  * User shall free returned list when not used any more.
  *
- * /param ts timestamp to compare.
- * /param elem returned list. NULL on error of if zero elements.
- * /param limit maximum number of objects to return. 0 means unlimited.
+ * \param ts timestamp to compare.
+ * \param elem returned list. NULL on error of if zero elements.
+ * \param limit maximum number of objects to return. 0 means unlimited.
  *
- * /return number of returned objects on success.
- * /return -1 on error
+ * \return number of returned objects on success.
+ * \return -1 on error
  */
 int cobj_get_timestamp(uint64_t ts, cobj_elem_t **elem, int limit);
 
-#endif // _CALL_OBJ_H_
+#endif /* _CALL_OBJ_H_ */