doxygen comment fixes (escapes, missing parameters, syntax errors) all over the place

modules/pdb/pdb.c

@@ -1,6 +1,4 @@
 /*
- * $Id: carrierroute.c 4712 2008-08-22 17:05:16Z henningw $
- *
  * Copyright (C) 2009 1&1 Internet AG
  *
  * This file is part of sip-router, a free SIP server.
@@ -46,7 +44,7 @@ MODULE_VERSION
 #define NETBUFSIZE 200
 
 
-static char* modp_server = NULL;  /*!< format: <host>:<port>,... */
+static char* modp_server = NULL;  /*!< format: \<host\>:\<port\>,... */
 static int timeout = 50;  /*!< timeout for queries in milliseconds */
 static int timeoutlogs = -10;  /*!< for aggregating timeout logs */
 static int *active = NULL;

modules/tls/tls_cfg.c

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2010 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -15,11 +13,14 @@
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
-/** tls runtime configuration.
+
+/**
+ * SIP-router TLS support :: tls runtime configuration
  * @file tls_cfg.c
  * @ingroup: @tls
  * Module: @ref tls
  */
+
 /*
  * History:
  * --------
@@ -222,7 +223,7 @@ cfg_def_t	tls_cfg_def[] = {
  * @param path - path to be fixed. If it starts with '.' or '/' is left alone
  *               (forced "relative" or "absolute" path). Otherwise the path
  *               is considered to be relative to the main config file directory
- *               (e.g. for /etc/ser/ser.cfg => /etc/ser/<path>).
+ *               (e.g. for /etc/ser/ser.cfg => /etc/ser/\<path\>).
  * @param def - default value used if path->s is empty (path->s == 0).
  * @return  0 on success, -1 on error.
  */

modules/tls/tls_domain.c

@@ -1,8 +1,4 @@
 /*
- * $Id$
- *
- * TLS module - virtual configuration domain support
- *
  * Copyright (C) 2001-2003 FhG FOKUS
  * Copyright (C) 2005,2006 iptelorg GmbH
  *
@@ -18,7 +14,9 @@
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
-/** SIP-router TLS support :: Virtual domain configuration support.
+
+/**
+ * SIP-router TLS support :: Virtual domain configuration support
  * @file
  * @ingroup tls
  * Module: @ref tls
@@ -349,7 +347,7 @@ static int tls_foreach_CTX_in_cfg(tls_domains_cfg_t* cfg,
  * @param path - path to be fixed. If it starts with '.' or '/' is left alone
  *               (forced "relative" or "absolute" path). Otherwise the path
  *               is considered to be relative to the main config file directory
- *               (e.g. for /etc/ser/ser.cfg => /etc/ser/<path>).
+ *               (e.g. for /etc/ser/ser.cfg => /etc/ser/\<path\>).
  * @return  0 on success, -1 on error.
  */
 int fix_shm_pathname(str* path)

modules/tm/callid.c

@@ -27,9 +27,9 @@
  * \file 
  * \brief TM :: Fast Call-ID generator
  * 
- * Fast Call-ID generator. The Call-ID has the following form: <callid_nr>-<pid>@<ip>
+ * Fast Call-ID generator. The Call-ID has the following form: \<callid_nr>-\<pid\>\@\<ip\>
  * - callid_nr is initialized as a random number and continually increases
- * - <pid>@<ip> is kept in callid_suffix
+ * - \<pid\>\@\<ip\> is kept in callid_suffix
  * - both are separated by a '-'
  * \ingroup tm
  */
@@ -67,7 +67,7 @@ static str callid_suffix;
 
 /**
  * \brief Initialize the Call-ID generator, generates random prefix
- * \param 0 on success, -1 on error
+ * \return 0 on success, -1 on error
  */
 int init_callid(void)
 {
@@ -110,7 +110,7 @@ int init_callid(void)
 /**
  * \brief Child initialization, generates suffix
  * \param rank not used
- * \param 0 on success, -1 on error
+ * \return 0 on success, -1 on error
  */
 int child_init_callid(int rank) 
 {

modules/tm/callid.h

@@ -37,7 +37,7 @@
 
 /**
  * \brief Initialize the Call-ID generator, generates random prefix
- * \param 0 on success, -1 on error
+ * \return 0 on success, -1 on error
  */
 int init_callid(void);
 
@@ -45,7 +45,7 @@ int init_callid(void);
 /**
  * \brief Child initialization, generates suffix
  * \param rank not used
- * \param 0 on success, -1 on error
+ * \return 0 on success, -1 on error
  */
 int child_init_callid(int rank);
 

modules/tm/sip_msg.c

@@ -104,7 +104,7 @@ unsigned char lumps_are_cloned = 0;
 /**
  * @brief Wrapper function for msg_lump_cloner() with some additional sanity checks
  * @param shm_msg SIP message in shared memory
- * @param pgk_msg SIP message in private memory
+ * @param pkg_msg SIP message in private memory
  * @return 0 on success, -1 on error
  */
 int save_msg_lumps( struct sip_msg *shm_msg, struct sip_msg *pkg_msg)

modules/tm/sip_msg.h

@@ -111,7 +111,7 @@ extern unsigned char lumps_are_cloned;
 /**
  * @brief Wrapper function for msg_lump_cloner() with some additional sanity checks
  * @param shm_msg SIP message in shared memory
- * @param pgk_msg SIP message in private memory
+ * @param pkg_msg SIP message in private memory
  * @return 0 on success, -1 on error
  */
 int save_msg_lumps( struct sip_msg *shm_msg, struct sip_msg *pkg_msg);

modules_k/dialog/dlg_handlers.c

@@ -1,6 +1,4 @@
 /*
- * $Id$
- *
  * Copyright (C) 2006 Voice System SRL
  *
  * This file is part of Kamailio, a free SIP server.
@@ -188,7 +186,9 @@ static inline int add_dlg_rr_param(struct sip_msg *req, unsigned int entry,
  * Parse SIP message and populate leg informations. 
  * \param dlg the dialog to add cseq, contact & record_route
  * \param msg sip message
- * \param flag  0-for a request(INVITE), 1- for a reply(200 ok)
+ * \param t transaction
+ * \param leg type of the call leg
+ * \param tag SIP To tag
  * \return 0 on success, -1 on failure
  * \note for a request: get record route in normal order, for a reply get
  * in reverse order, skipping the ones from the request and the proxies' own

modules_k/dialog/dlg_handlers.h

@@ -1,6 +1,4 @@
 /*
- * $Id$
- *
  * Copyright (C) 2006 Voice System SRL
  *
  * This file is part of Kamailio, a free SIP server.
@@ -76,7 +74,9 @@ void destroy_dlg_handlers(void);
  * Parse SIP message and populate leg informations. 
  * \param dlg the dialog to add cseq, contact & record_route
  * \param msg sip message
- * \param flag  0-for a request(INVITE), 1- for a reply(200 ok)
+ * \param t transaction
+ * \param leg type of the call leg
+ * \param tag SIP To tag
  * \return 0 on success, -1 on failure
  * \note for a request: get record route in normal order, for a reply get
  * in reverse order, skipping the ones from the request and the proxies' own

modules_k/dialog/dlg_hash.c

@@ -1,6 +1,4 @@
 /*
- * $Id$
- *
  * Copyright (C) 2006 Voice System SRL
  * Copyright (C) 2011 Carsten Bock, [email protected]
  *
@@ -385,7 +383,8 @@ error:
  * \brief Lookup a dialog in the global list
  * \param h_entry number of the hash table entry
  * \param h_id id of the hash table entry
- * \return dialog on success, NULL on failure
+ * \param del will set to 1 if dialog is deleted
+ * \return dialog structure on success, NULL on failure or if not found
  */
 struct dlg_cell* lookup_dlg( unsigned int h_entry, unsigned int h_id, unsigned int *del)
 {
@@ -432,7 +431,8 @@ not_found:
  * \param ftag from tag
  * \param ttag to tag
  * \param dir direction
- * \return dialog structure on success, NULL on failure
+ * \param del will set to 1 if dialog is deleted
+ * \return dialog structure on success, NULL on failure or if not found
  */
 static inline struct dlg_cell* internal_get_dlg(unsigned int h_entry,
 						str *callid, str *ftag, str *ttag, unsigned int *dir,
@@ -487,6 +487,7 @@ not_found:
  * \param ftag from tag
  * \param ttag to tag
  * \param dir direction
+ * \param del deleted dialog information
  * \return dialog structure on success, NULL on failure
  */
 struct dlg_cell* get_dlg( str *callid, str *ftag, str *ttag, unsigned int *dir,
@@ -553,6 +554,7 @@ void link_dlg(struct dlg_cell *dlg, int n)
  * \brief Unreference a dialog without locking
  * \param _dlg dialog
  * \param _cnt decrement for the reference counter
+ * \param _d_entry dialog entry
  */
 #define unref_dlg_unsafe(_dlg,_cnt,_d_entry)   \
 	do { \

modules_k/dialog/dlg_hash.h

@@ -1,6 +1,4 @@
 /*
- * $Id$
- *
  * Copyright (C) 2006 Voice System SRL
  * Copyright (C) 2011 Carsten Bock, [email protected]
  *
@@ -257,8 +255,8 @@ int dlg_set_toroute(struct dlg_cell *dlg, str *route);
  * \brief Lookup a dialog in the global list
  * \param h_entry number of the hash table entry
  * \param h_id id of the hash table entry
- * \param del unless null, flag that is set if dialog is in "deleted" state
- * \return dialog on success, NULL on failure
+ * \param del will set to 1 if dialog is deleted
+ * \return dialog structure on success, NULL on failure or if not found
  */
 struct dlg_cell* lookup_dlg( unsigned int h_entry, unsigned int h_id, unsigned int *del);
 
@@ -352,6 +350,7 @@ struct mi_root * mi_terminate_dlgs(struct mi_root *cmd_tree, void *param );
 /*!
  * \brief Check if a dialog structure matches to a SIP message dialog
  * \param dlg dialog structure
+ * \param callid SIP message Call-ID
  * \param ftag SIP message from tag
  * \param ttag SIP message to tag
  * \param dir direction of the message, if DLG_DIR_NONE it will set

sr_module.c

@@ -1,5 +1,4 @@
-/* $Id$
- *
+/*
  * Copyright (C) 2001-2003 FhG Fokus
  *
  * This file is part of ser, a free SIP server.
@@ -377,16 +376,18 @@ static inline int version_control(void *handle, char *path)
 	return 0;
 }
 
-/** load a sr module.
+/**
+ * \brief load a sr module
+ * 
  * tries to load the module specified by mod_path.
  * If mod_path is 'modname' or 'modname.so' then
- *  <MODS_DIR>/<modname>.so will be tried and if this fails
- *  <MODS_DIR>/<modname>/<modname>.so
+ *  \<MODS_DIR\>/\<modname\>.so will be tried and if this fails
+ *  \<MODS_DIR\>/\<modname\>/\<modname\>.so
  * If mod_path contain a '/' it is assumed to be the 
  * path to the module and tried first. If fails and mod_path is not
  * absolute path (not starting with '/') then will try:
- *   <MODS_DIR>/mod_path
- * @param modname - path or module name
+ * \<MODS_DIR\>/mod_path
+ * @param mod_path path or module name
  * @return 0 on success , <0 on error
  */
 int load_module(char* mod_path)

timer_proc.c

@@ -43,9 +43,10 @@
 #include <unistd.h>
 
 
-/** update internal counters for running new dummy timers
- *  @param timers - number of dummy timer processes
- *  @return - 0 on success; -1 on error
+/**
+ * \brief update internal counters for running new dummy timers
+ * @param timers number of dummy timer processes
+ * @return 0 on success; -1 on error
  */
 int register_dummy_timers(int timers)
 {
@@ -55,21 +56,23 @@ int register_dummy_timers(int timers)
 	return 0;
 }
 
-/** forks a separate simple sleep() periodic timer.
-  * Forks a very basic periodic timer process, that just sleep()s for 
-  * the specified interval and then calls the timer function.
-  * The new "dummy timer" process execution start immediately, the sleep()
-  * is called first (so the first call to the timer function will happen
-  * <interval> seconds after the call to fork_dummy_timer)
-  * @param child_id - @see fork_process()
-  * @param desc     - @see fork_process()
-  * @param make_sock - @see fork_process()
-  * @param f         - timer function/callback
-  * @param param     - parameter passed to the timer function
-  * @param interval  - interval in seconds.
-  * @return - pid of the new process on success, -1 on error
-  *           (doesn't return anything in the child process)
-  */
+/**
+ * \brief Forks a separate simple sleep() periodic timer
+ * 
+ * Forks a very basic periodic timer process, that just sleep()s for 
+ * the specified interval and then calls the timer function.
+ * The new "dummy timer" process execution start immediately, the sleep()
+ * is called first (so the first call to the timer function will happen
+ * \<interval\> seconds after the call to fork_dummy_timer)
+ * @param child_id  @see fork_process()
+ * @param desc      @see fork_process()
+ * @param make_sock @see fork_process()
+ * @param f         timer function/callback
+ * @param param     parameter passed to the timer function
+ * @param interval  interval in seconds.
+ * @return pid of the new process on success, -1 on error
+ * (doesn't return anything in the child process)
+ */
 int fork_dummy_timer(int child_id, char* desc, int make_sock,
 						timer_function* f, void* param, int interval)
 {
@@ -93,31 +96,33 @@ int fork_dummy_timer(int child_id, char* desc, int make_sock,
 
 
 
-/** forks a timer process based on the local timer.
- *  Forks a separate timer process running a local_timer.h type of timer
- *  A pointer to the local_timer handle (allocated in shared memory) is
- *  returned in lt_h. It can be used to add/delete more timers at runtime
- *  (via local_timer_add()/local_timer_del() a.s.o).
- *  If timers are added from separate processes, some form of locking must be
- *  used (all the calls to local_timer* must be enclosed by locks if it
- *  cannot be guaranteed that they cannot execute in the same time)
- *  The timer "engine" must be run manually from the child process. For
- *  example a very simple local timer process that just runs a single 
- *  periodic timer can be started in the following way:
- *      struct local_timer* lt_h;
- *
- *      pid=fork_local_timer_process(...., &lt_h);
- *      if (pid==0){
+/**
+ * \brief Forks a timer process based on the local timer
+ * 
+ * Forks a separate timer process running a local_timer.h type of timer
+ * A pointer to the local_timer handle (allocated in shared memory) is
+ * returned in lt_h. It can be used to add/delete more timers at runtime
+ * (via local_timer_add()/local_timer_del() a.s.o).
+ * If timers are added from separate processes, some form of locking must be
+ * used (all the calls to local_timer* must be enclosed by locks if it
+ * cannot be guaranteed that they cannot execute in the same time)
+ * The timer "engine" must be run manually from the child process. For
+ * example a very simple local timer process that just runs a single 
+ * periodic timer can be started in the following way:
+ * struct local_timer* lt_h;
+ * 
+ * pid=fork_local_timer_process(...., &lt_h);
+ * if (pid==0){
  *          timer_init(&my_timer, my_timer_f, 0, 0);
  *          local_timer_add(&lt_h, &my_timer, S_TO_TICKS(10), get_ticks_raw());
  *          while(1) { sleep(1); local_timer_run(lt, get_ticks_raw()); }
- *      }
+ * }
  *
- * @param child_id - @see fork_process()
- * @param desc     - @see fork_process()
- * @param make_sock - @see fork_process()
- * @param lt_h      - local_timer handler
- * @return - pid to the parent, 0 to the child, -1 if error.
+ * @param child_id  @see fork_process()
+ * @param desc      @see fork_process()
+ * @param make_sock @see fork_process()
+ * @param lt_h      local_timer handler
+ * @return pid to the parent, 0 to the child, -1 if error.
  */
 int fork_local_timer_process(int child_id, char* desc, int make_sock,
 						struct local_timer** lt_h)

timer_proc.h

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- * 
  * Copyright (C) 2009 iptelorg GmbH
  *
  * Permission to use, copy, modify, and distribute this software for any
@@ -36,14 +34,63 @@
 
 #include "local_timer.h"
 
-/** @brief register the number of extra dummy timer processes */
+/**
+ * \brief update internal counters for running new dummy timers
+ * @param timers number of dummy timer processes
+ * @return 0 on success; -1 on error
+ */
 int register_dummy_timers(int timers);
 
-/** @brief forks a separate simple sleep() periodic timer */
+
+/**
+ * \brief Forks a separate simple sleep() periodic timer
+ * 
+ * Forks a very basic periodic timer process, that just sleep()s for 
+ * the specified interval and then calls the timer function.
+ * The new "dummy timer" process execution start immediately, the sleep()
+ * is called first (so the first call to the timer function will happen
+ * \<interval\> seconds after the call to fork_dummy_timer)
+ * @param child_id  @see fork_process()
+ * @param desc      @see fork_process()
+ * @param make_sock @see fork_process()
+ * @param f         timer function/callback
+ * @param param     parameter passed to the timer function
+ * @param interval  interval in seconds.
+ * @return pid of the new process on success, -1 on error
+ * (doesn't return anything in the child process)
+ */
 int fork_dummy_timer(int child_id, char* desc, int make_sock,
 						timer_function* f, void* param, int interval);
 
-/** @briefforks a timer process based on the local timer */
+
+/**
+ * \brief Forks a timer process based on the local timer
+ * 
+ * Forks a separate timer process running a local_timer.h type of timer
+ * A pointer to the local_timer handle (allocated in shared memory) is
+ * returned in lt_h. It can be used to add/delete more timers at runtime
+ * (via local_timer_add()/local_timer_del() a.s.o).
+ * If timers are added from separate processes, some form of locking must be
+ * used (all the calls to local_timer* must be enclosed by locks if it
+ * cannot be guaranteed that they cannot execute in the same time)
+ * The timer "engine" must be run manually from the child process. For
+ * example a very simple local timer process that just runs a single 
+ * periodic timer can be started in the following way:
+ * struct local_timer* lt_h;
+ * 
+ * pid=fork_local_timer_process(...., &lt_h);
+ * if (pid==0){
+ *          timer_init(&my_timer, my_timer_f, 0, 0);
+ *          local_timer_add(&lt_h, &my_timer, S_TO_TICKS(10), get_ticks_raw());
+ *          while(1) { sleep(1); local_timer_run(lt, get_ticks_raw()); }
+ * }
+ *
+ * @param child_id  @see fork_process()
+ * @param desc      @see fork_process()
+ * @param make_sock @see fork_process()
+ * @param lt_h      local_timer handler
+ * @return pid to the parent, 0 to the child, -1 if error.
+ */
 int fork_local_timer_process(int child_id, char* desc, int make_sock,
 						struct local_timer** lt_h);
 

usr_avp.c

@@ -1,6 +1,4 @@
 /*
- * $Id$
- *
  * Copyright (C) 2001-2003 FhG Fokus
  *
  * This file is part of ser, a free SIP server.
@@ -860,15 +858,15 @@ int parse_avp_name( str *name, int *type, int_str *avp_name, int *index)
  *       - "<track><class>.<name>[<index>]"      (e.g:  fd.bar[2])
  *       - "<string>"                            (e.g.: foo)
  * Where:
- *          <string> = ascii string
- *          <id>   = ascii string w/o '[', ']', '.' and '/'
- *          <name> = <id> | '/' regex '/'
+ *          \<string\> = ascii string
+ *          \<id\>   = ascii string w/o '[', ']', '.' and '/'
+ *          \<name\> = \<id\> | '/' regex '/'
  *                   (Note: regex use is deprecated)
- *          <track> = 'f' | 't'
+ *          \<track\> = 'f' | 't'
  *                   (from or to)
- *          <class> = 'r' | 'u' | 'd' | 'g'
+ *          \<class\> = 'r' | 'u' | 'd' | 'g'
  *                    (uri, user, domain or global)
- *          <index> = <number> | '-' <number> | ''
+ *          \<index\> = \<number\> | '-' \<number\> | ''
  *                    (the avp index, if missing it means AVP_INDEX_ALL, but
  *                     it's use is deprecated)
  * More examples: