Browse code

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

Henning Westerholt authored on 22/07/2011 07:23:18
Showing 15 changed files
... ...
@@ -1,6 +1,4 @@
1 1
 /*
2
- * $Id: carrierroute.c 4712 2008-08-22 17:05:16Z henningw $
3
- *
4 2
  * Copyright (C) 2009 1&1 Internet AG
5 3
  *
6 4
  * This file is part of sip-router, a free SIP server.
... ...
@@ -46,7 +44,7 @@ MODULE_VERSION
46 46
 #define NETBUFSIZE 200
47 47
 
48 48
 
49
-static char* modp_server = NULL;  /*!< format: <host>:<port>,... */
49
+static char* modp_server = NULL;  /*!< format: \<host\>:\<port\>,... */
50 50
 static int timeout = 50;  /*!< timeout for queries in milliseconds */
51 51
 static int timeoutlogs = -10;  /*!< for aggregating timeout logs */
52 52
 static int *active = NULL;
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2010 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -15,11 +13,14 @@
15 15
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 16
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 17
  */
18
-/** tls runtime configuration.
18
+
19
+/**
20
+ * SIP-router TLS support :: tls runtime configuration
19 21
  * @file tls_cfg.c
20 22
  * @ingroup: @tls
21 23
  * Module: @ref tls
22 24
  */
25
+
23 26
 /*
24 27
  * History:
25 28
  * --------
... ...
@@ -222,7 +223,7 @@ cfg_def_t	tls_cfg_def[] = {
222 222
  * @param path - path to be fixed. If it starts with '.' or '/' is left alone
223 223
  *               (forced "relative" or "absolute" path). Otherwise the path
224 224
  *               is considered to be relative to the main config file directory
225
- *               (e.g. for /etc/ser/ser.cfg => /etc/ser/<path>).
225
+ *               (e.g. for /etc/ser/ser.cfg => /etc/ser/\<path\>).
226 226
  * @param def - default value used if path->s is empty (path->s == 0).
227 227
  * @return  0 on success, -1 on error.
228 228
  */
... ...
@@ -1,8 +1,4 @@
1 1
 /*
2
- * $Id$
3
- *
4
- * TLS module - virtual configuration domain support
5
- *
6 2
  * Copyright (C) 2001-2003 FhG FOKUS
7 3
  * Copyright (C) 2005,2006 iptelorg GmbH
8 4
  *
... ...
@@ -18,7 +14,9 @@
18 18
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19 19
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 20
  */
21
-/** SIP-router TLS support :: Virtual domain configuration support.
21
+
22
+/**
23
+ * SIP-router TLS support :: Virtual domain configuration support
22 24
  * @file
23 25
  * @ingroup tls
24 26
  * Module: @ref tls
... ...
@@ -349,7 +347,7 @@ static int tls_foreach_CTX_in_cfg(tls_domains_cfg_t* cfg,
349 349
  * @param path - path to be fixed. If it starts with '.' or '/' is left alone
350 350
  *               (forced "relative" or "absolute" path). Otherwise the path
351 351
  *               is considered to be relative to the main config file directory
352
- *               (e.g. for /etc/ser/ser.cfg => /etc/ser/<path>).
352
+ *               (e.g. for /etc/ser/ser.cfg => /etc/ser/\<path\>).
353 353
  * @return  0 on success, -1 on error.
354 354
  */
355 355
 int fix_shm_pathname(str* path)
... ...
@@ -27,9 +27,9 @@
27 27
  * \file 
28 28
  * \brief TM :: Fast Call-ID generator
29 29
  * 
30
- * Fast Call-ID generator. The Call-ID has the following form: <callid_nr>-<pid>@<ip>
30
+ * Fast Call-ID generator. The Call-ID has the following form: \<callid_nr>-\<pid\>\@\<ip\>
31 31
  * - callid_nr is initialized as a random number and continually increases
32
- * - <pid>@<ip> is kept in callid_suffix
32
+ * - \<pid\>\@\<ip\> is kept in callid_suffix
33 33
  * - both are separated by a '-'
34 34
  * \ingroup tm
35 35
  */
... ...
@@ -67,7 +67,7 @@ static str callid_suffix;
67 67
 
68 68
 /**
69 69
  * \brief Initialize the Call-ID generator, generates random prefix
70
- * \param 0 on success, -1 on error
70
+ * \return 0 on success, -1 on error
71 71
  */
72 72
 int init_callid(void)
73 73
 {
... ...
@@ -110,7 +110,7 @@ int init_callid(void)
110 110
 /**
111 111
  * \brief Child initialization, generates suffix
112 112
  * \param rank not used
113
- * \param 0 on success, -1 on error
113
+ * \return 0 on success, -1 on error
114 114
  */
115 115
 int child_init_callid(int rank) 
116 116
 {
... ...
@@ -37,7 +37,7 @@
37 37
 
38 38
 /**
39 39
  * \brief Initialize the Call-ID generator, generates random prefix
40
- * \param 0 on success, -1 on error
40
+ * \return 0 on success, -1 on error
41 41
  */
42 42
 int init_callid(void);
43 43
 
... ...
@@ -45,7 +45,7 @@ int init_callid(void);
45 45
 /**
46 46
  * \brief Child initialization, generates suffix
47 47
  * \param rank not used
48
- * \param 0 on success, -1 on error
48
+ * \return 0 on success, -1 on error
49 49
  */
50 50
 int child_init_callid(int rank);
51 51
 
... ...
@@ -104,7 +104,7 @@ unsigned char lumps_are_cloned = 0;
104 104
 /**
105 105
  * @brief Wrapper function for msg_lump_cloner() with some additional sanity checks
106 106
  * @param shm_msg SIP message in shared memory
107
- * @param pgk_msg SIP message in private memory
107
+ * @param pkg_msg SIP message in private memory
108 108
  * @return 0 on success, -1 on error
109 109
  */
110 110
 int save_msg_lumps( struct sip_msg *shm_msg, struct sip_msg *pkg_msg)
... ...
@@ -111,7 +111,7 @@ extern unsigned char lumps_are_cloned;
111 111
 /**
112 112
  * @brief Wrapper function for msg_lump_cloner() with some additional sanity checks
113 113
  * @param shm_msg SIP message in shared memory
114
- * @param pgk_msg SIP message in private memory
114
+ * @param pkg_msg SIP message in private memory
115 115
  * @return 0 on success, -1 on error
116 116
  */
117 117
 int save_msg_lumps( struct sip_msg *shm_msg, struct sip_msg *pkg_msg);
... ...
@@ -1,6 +1,4 @@
1 1
 /*
2
- * $Id$
3
- *
4 2
  * Copyright (C) 2006 Voice System SRL
5 3
  *
6 4
  * 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,
188 188
  * Parse SIP message and populate leg informations. 
189 189
  * \param dlg the dialog to add cseq, contact & record_route
190 190
  * \param msg sip message
191
- * \param flag  0-for a request(INVITE), 1- for a reply(200 ok)
191
+ * \param t transaction
192
+ * \param leg type of the call leg
193
+ * \param tag SIP To tag
192 194
  * \return 0 on success, -1 on failure
193 195
  * \note for a request: get record route in normal order, for a reply get
194 196
  * in reverse order, skipping the ones from the request and the proxies' own
... ...
@@ -1,6 +1,4 @@
1 1
 /*
2
- * $Id$
3
- *
4 2
  * Copyright (C) 2006 Voice System SRL
5 3
  *
6 4
  * This file is part of Kamailio, a free SIP server.
... ...
@@ -76,7 +74,9 @@ void destroy_dlg_handlers(void);
76 76
  * Parse SIP message and populate leg informations. 
77 77
  * \param dlg the dialog to add cseq, contact & record_route
78 78
  * \param msg sip message
79
- * \param flag  0-for a request(INVITE), 1- for a reply(200 ok)
79
+ * \param t transaction
80
+ * \param leg type of the call leg
81
+ * \param tag SIP To tag
80 82
  * \return 0 on success, -1 on failure
81 83
  * \note for a request: get record route in normal order, for a reply get
82 84
  * in reverse order, skipping the ones from the request and the proxies' own
... ...
@@ -1,6 +1,4 @@
1 1
 /*
2
- * $Id$
3
- *
4 2
  * Copyright (C) 2006 Voice System SRL
5 3
  * Copyright (C) 2011 Carsten Bock, carsten@ng-voice.com
6 4
  *
... ...
@@ -385,7 +383,8 @@ error:
385 385
  * \brief Lookup a dialog in the global list
386 386
  * \param h_entry number of the hash table entry
387 387
  * \param h_id id of the hash table entry
388
- * \return dialog on success, NULL on failure
388
+ * \param del will set to 1 if dialog is deleted
389
+ * \return dialog structure on success, NULL on failure or if not found
389 390
  */
390 391
 struct dlg_cell* lookup_dlg( unsigned int h_entry, unsigned int h_id, unsigned int *del)
391 392
 {
... ...
@@ -432,7 +431,8 @@ not_found:
432 432
  * \param ftag from tag
433 433
  * \param ttag to tag
434 434
  * \param dir direction
435
- * \return dialog structure on success, NULL on failure
435
+ * \param del will set to 1 if dialog is deleted
436
+ * \return dialog structure on success, NULL on failure or if not found
436 437
  */
437 438
 static inline struct dlg_cell* internal_get_dlg(unsigned int h_entry,
438 439
 						str *callid, str *ftag, str *ttag, unsigned int *dir,
... ...
@@ -487,6 +487,7 @@ not_found:
487 487
  * \param ftag from tag
488 488
  * \param ttag to tag
489 489
  * \param dir direction
490
+ * \param del deleted dialog information
490 491
  * \return dialog structure on success, NULL on failure
491 492
  */
492 493
 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)
553 553
  * \brief Unreference a dialog without locking
554 554
  * \param _dlg dialog
555 555
  * \param _cnt decrement for the reference counter
556
+ * \param _d_entry dialog entry
556 557
  */
557 558
 #define unref_dlg_unsafe(_dlg,_cnt,_d_entry)   \
558 559
 	do { \
... ...
@@ -1,6 +1,4 @@
1 1
 /*
2
- * $Id$
3
- *
4 2
  * Copyright (C) 2006 Voice System SRL
5 3
  * Copyright (C) 2011 Carsten Bock, carsten@ng-voice.com
6 4
  *
... ...
@@ -257,8 +255,8 @@ int dlg_set_toroute(struct dlg_cell *dlg, str *route);
257 257
  * \brief Lookup a dialog in the global list
258 258
  * \param h_entry number of the hash table entry
259 259
  * \param h_id id of the hash table entry
260
- * \param del unless null, flag that is set if dialog is in "deleted" state
261
- * \return dialog on success, NULL on failure
260
+ * \param del will set to 1 if dialog is deleted
261
+ * \return dialog structure on success, NULL on failure or if not found
262 262
  */
263 263
 struct dlg_cell* lookup_dlg( unsigned int h_entry, unsigned int h_id, unsigned int *del);
264 264
 
... ...
@@ -352,6 +350,7 @@ struct mi_root * mi_terminate_dlgs(struct mi_root *cmd_tree, void *param );
352 352
 /*!
353 353
  * \brief Check if a dialog structure matches to a SIP message dialog
354 354
  * \param dlg dialog structure
355
+ * \param callid SIP message Call-ID
355 356
  * \param ftag SIP message from tag
356 357
  * \param ttag SIP message to tag
357 358
  * \param dir direction of the message, if DLG_DIR_NONE it will set
... ...
@@ -1,5 +1,4 @@
1
-/* $Id$
2
- *
1
+/*
3 2
  * Copyright (C) 2001-2003 FhG Fokus
4 3
  *
5 4
  * This file is part of ser, a free SIP server.
... ...
@@ -377,16 +376,18 @@ static inline int version_control(void *handle, char *path)
377 377
 	return 0;
378 378
 }
379 379
 
380
-/** load a sr module.
380
+/**
381
+ * \brief load a sr module
382
+ * 
381 383
  * tries to load the module specified by mod_path.
382 384
  * If mod_path is 'modname' or 'modname.so' then
383
- *  <MODS_DIR>/<modname>.so will be tried and if this fails
384
- *  <MODS_DIR>/<modname>/<modname>.so
385
+ *  \<MODS_DIR\>/\<modname\>.so will be tried and if this fails
386
+ *  \<MODS_DIR\>/\<modname\>/\<modname\>.so
385 387
  * If mod_path contain a '/' it is assumed to be the 
386 388
  * path to the module and tried first. If fails and mod_path is not
387 389
  * absolute path (not starting with '/') then will try:
388
- *   <MODS_DIR>/mod_path
389
- * @param modname - path or module name
390
+ * \<MODS_DIR\>/mod_path
391
+ * @param mod_path path or module name
390 392
  * @return 0 on success , <0 on error
391 393
  */
392 394
 int load_module(char* mod_path)
... ...
@@ -43,9 +43,10 @@
43 43
 #include <unistd.h>
44 44
 
45 45
 
46
-/** update internal counters for running new dummy timers
47
- *  @param timers - number of dummy timer processes
48
- *  @return - 0 on success; -1 on error
46
+/**
47
+ * \brief update internal counters for running new dummy timers
48
+ * @param timers number of dummy timer processes
49
+ * @return 0 on success; -1 on error
49 50
  */
50 51
 int register_dummy_timers(int timers)
51 52
 {
... ...
@@ -55,21 +56,23 @@ int register_dummy_timers(int timers)
55 55
 	return 0;
56 56
 }
57 57
 
58
-/** forks a separate simple sleep() periodic timer.
59
-  * Forks a very basic periodic timer process, that just sleep()s for 
60
-  * the specified interval and then calls the timer function.
61
-  * The new "dummy timer" process execution start immediately, the sleep()
62
-  * is called first (so the first call to the timer function will happen
63
-  * <interval> seconds after the call to fork_dummy_timer)
64
-  * @param child_id - @see fork_process()
65
-  * @param desc     - @see fork_process()
66
-  * @param make_sock - @see fork_process()
67
-  * @param f         - timer function/callback
68
-  * @param param     - parameter passed to the timer function
69
-  * @param interval  - interval in seconds.
70
-  * @return - pid of the new process on success, -1 on error
71
-  *           (doesn't return anything in the child process)
72
-  */
58
+/**
59
+ * \brief Forks a separate simple sleep() periodic timer
60
+ * 
61
+ * Forks a very basic periodic timer process, that just sleep()s for 
62
+ * the specified interval and then calls the timer function.
63
+ * The new "dummy timer" process execution start immediately, the sleep()
64
+ * is called first (so the first call to the timer function will happen
65
+ * \<interval\> seconds after the call to fork_dummy_timer)
66
+ * @param child_id  @see fork_process()
67
+ * @param desc      @see fork_process()
68
+ * @param make_sock @see fork_process()
69
+ * @param f         timer function/callback
70
+ * @param param     parameter passed to the timer function
71
+ * @param interval  interval in seconds.
72
+ * @return pid of the new process on success, -1 on error
73
+ * (doesn't return anything in the child process)
74
+ */
73 75
 int fork_dummy_timer(int child_id, char* desc, int make_sock,
74 76
 						timer_function* f, void* param, int interval)
75 77
 {
... ...
@@ -93,31 +96,33 @@ int fork_dummy_timer(int child_id, char* desc, int make_sock,
93 93
 
94 94
 
95 95
 
96
-/** forks a timer process based on the local timer.
97
- *  Forks a separate timer process running a local_timer.h type of timer
98
- *  A pointer to the local_timer handle (allocated in shared memory) is
99
- *  returned in lt_h. It can be used to add/delete more timers at runtime
100
- *  (via local_timer_add()/local_timer_del() a.s.o).
101
- *  If timers are added from separate processes, some form of locking must be
102
- *  used (all the calls to local_timer* must be enclosed by locks if it
103
- *  cannot be guaranteed that they cannot execute in the same time)
104
- *  The timer "engine" must be run manually from the child process. For
105
- *  example a very simple local timer process that just runs a single 
106
- *  periodic timer can be started in the following way:
107
- *      struct local_timer* lt_h;
108
- *
109
- *      pid=fork_local_timer_process(...., &lt_h);
110
- *      if (pid==0){
96
+/**
97
+ * \brief Forks a timer process based on the local timer
98
+ * 
99
+ * Forks a separate timer process running a local_timer.h type of timer
100
+ * A pointer to the local_timer handle (allocated in shared memory) is
101
+ * returned in lt_h. It can be used to add/delete more timers at runtime
102
+ * (via local_timer_add()/local_timer_del() a.s.o).
103
+ * If timers are added from separate processes, some form of locking must be
104
+ * used (all the calls to local_timer* must be enclosed by locks if it
105
+ * cannot be guaranteed that they cannot execute in the same time)
106
+ * The timer "engine" must be run manually from the child process. For
107
+ * example a very simple local timer process that just runs a single 
108
+ * periodic timer can be started in the following way:
109
+ * struct local_timer* lt_h;
110
+ * 
111
+ * pid=fork_local_timer_process(...., &lt_h);
112
+ * if (pid==0){
111 113
  *          timer_init(&my_timer, my_timer_f, 0, 0);
112 114
  *          local_timer_add(&lt_h, &my_timer, S_TO_TICKS(10), get_ticks_raw());
113 115
  *          while(1) { sleep(1); local_timer_run(lt, get_ticks_raw()); }
114
- *      }
116
+ * }
115 117
  *
116
- * @param child_id - @see fork_process()
117
- * @param desc     - @see fork_process()
118
- * @param make_sock - @see fork_process()
119
- * @param lt_h      - local_timer handler
120
- * @return - pid to the parent, 0 to the child, -1 if error.
118
+ * @param child_id  @see fork_process()
119
+ * @param desc      @see fork_process()
120
+ * @param make_sock @see fork_process()
121
+ * @param lt_h      local_timer handler
122
+ * @return pid to the parent, 0 to the child, -1 if error.
121 123
  */
122 124
 int fork_local_timer_process(int child_id, char* desc, int make_sock,
123 125
 						struct local_timer** lt_h)
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2009 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -36,14 +34,63 @@
36 36
 
37 37
 #include "local_timer.h"
38 38
 
39
-/** @brief register the number of extra dummy timer processes */
39
+/**
40
+ * \brief update internal counters for running new dummy timers
41
+ * @param timers number of dummy timer processes
42
+ * @return 0 on success; -1 on error
43
+ */
40 44
 int register_dummy_timers(int timers);
41 45
 
42
-/** @brief forks a separate simple sleep() periodic timer */
46
+
47
+/**
48
+ * \brief Forks a separate simple sleep() periodic timer
49
+ * 
50
+ * Forks a very basic periodic timer process, that just sleep()s for 
51
+ * the specified interval and then calls the timer function.
52
+ * The new "dummy timer" process execution start immediately, the sleep()
53
+ * is called first (so the first call to the timer function will happen
54
+ * \<interval\> seconds after the call to fork_dummy_timer)
55
+ * @param child_id  @see fork_process()
56
+ * @param desc      @see fork_process()
57
+ * @param make_sock @see fork_process()
58
+ * @param f         timer function/callback
59
+ * @param param     parameter passed to the timer function
60
+ * @param interval  interval in seconds.
61
+ * @return pid of the new process on success, -1 on error
62
+ * (doesn't return anything in the child process)
63
+ */
43 64
 int fork_dummy_timer(int child_id, char* desc, int make_sock,
44 65
 						timer_function* f, void* param, int interval);
45 66
 
46
-/** @briefforks a timer process based on the local timer */
67
+
68
+/**
69
+ * \brief Forks a timer process based on the local timer
70
+ * 
71
+ * Forks a separate timer process running a local_timer.h type of timer
72
+ * A pointer to the local_timer handle (allocated in shared memory) is
73
+ * returned in lt_h. It can be used to add/delete more timers at runtime
74
+ * (via local_timer_add()/local_timer_del() a.s.o).
75
+ * If timers are added from separate processes, some form of locking must be
76
+ * used (all the calls to local_timer* must be enclosed by locks if it
77
+ * cannot be guaranteed that they cannot execute in the same time)
78
+ * The timer "engine" must be run manually from the child process. For
79
+ * example a very simple local timer process that just runs a single 
80
+ * periodic timer can be started in the following way:
81
+ * struct local_timer* lt_h;
82
+ * 
83
+ * pid=fork_local_timer_process(...., &lt_h);
84
+ * if (pid==0){
85
+ *          timer_init(&my_timer, my_timer_f, 0, 0);
86
+ *          local_timer_add(&lt_h, &my_timer, S_TO_TICKS(10), get_ticks_raw());
87
+ *          while(1) { sleep(1); local_timer_run(lt, get_ticks_raw()); }
88
+ * }
89
+ *
90
+ * @param child_id  @see fork_process()
91
+ * @param desc      @see fork_process()
92
+ * @param make_sock @see fork_process()
93
+ * @param lt_h      local_timer handler
94
+ * @return pid to the parent, 0 to the child, -1 if error.
95
+ */
47 96
 int fork_local_timer_process(int child_id, char* desc, int make_sock,
48 97
 						struct local_timer** lt_h);
49 98
 
... ...
@@ -1,6 +1,4 @@
1 1
 /*
2
- * $Id$
3
- *
4 2
  * Copyright (C) 2001-2003 FhG Fokus
5 3
  *
6 4
  * 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)
860 860
  *       - "<track><class>.<name>[<index>]"      (e.g:  fd.bar[2])
861 861
  *       - "<string>"                            (e.g.: foo)
862 862
  * Where:
863
- *          <string> = ascii string
864
- *          <id>   = ascii string w/o '[', ']', '.' and '/'
865
- *          <name> = <id> | '/' regex '/'
863
+ *          \<string\> = ascii string
864
+ *          \<id\>   = ascii string w/o '[', ']', '.' and '/'
865
+ *          \<name\> = \<id\> | '/' regex '/'
866 866
  *                   (Note: regex use is deprecated)
867
- *          <track> = 'f' | 't'
867
+ *          \<track\> = 'f' | 't'
868 868
  *                   (from or to)
869
- *          <class> = 'r' | 'u' | 'd' | 'g'
869
+ *          \<class\> = 'r' | 'u' | 'd' | 'g'
870 870
  *                    (uri, user, domain or global)
871
- *          <index> = <number> | '-' <number> | ''
871
+ *          \<index\> = \<number\> | '-' \<number\> | ''
872 872
  *                    (the avp index, if missing it means AVP_INDEX_ALL, but
873 873
  *                     it's use is deprecated)
874 874
  * More examples: