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 44
 #define NETBUFSIZE 200
47 45
 
48 46
 
49
-static char* modp_server = NULL;  /*!< format: <host>:<port>,... */
47
+static char* modp_server = NULL;  /*!< format: \<host\>:\<port\>,... */
50 48
 static int timeout = 50;  /*!< timeout for queries in milliseconds */
51 49
 static int timeoutlogs = -10;  /*!< for aggregating timeout logs */
52 50
 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 13
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 14
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 15
  */
18
-/** tls runtime configuration.
16
+
17
+/**
18
+ * SIP-router TLS support :: tls runtime configuration
19 19
  * @file tls_cfg.c
20 20
  * @ingroup: @tls
21 21
  * Module: @ref tls
22 22
  */
23
+
23 24
 /*
24 25
  * History:
25 26
  * --------
... ...
@@ -222,7 +223,7 @@ cfg_def_t	tls_cfg_def[] = {
222 223
  * @param path - path to be fixed. If it starts with '.' or '/' is left alone
223 224
  *               (forced "relative" or "absolute" path). Otherwise the path
224 225
  *               is considered to be relative to the main config file directory
225
- *               (e.g. for /etc/ser/ser.cfg => /etc/ser/<path>).
226
+ *               (e.g. for /etc/ser/ser.cfg => /etc/ser/\<path\>).
226 227
  * @param def - default value used if path->s is empty (path->s == 0).
227 228
  * @return  0 on success, -1 on error.
228 229
  */
... ...
@@ -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 14
  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19 15
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20 16
  */
21
-/** SIP-router TLS support :: Virtual domain configuration support.
17
+
18
+/**
19
+ * SIP-router TLS support :: Virtual domain configuration support
22 20
  * @file
23 21
  * @ingroup tls
24 22
  * Module: @ref tls
... ...
@@ -349,7 +347,7 @@ static int tls_foreach_CTX_in_cfg(tls_domains_cfg_t* cfg,
349 347
  * @param path - path to be fixed. If it starts with '.' or '/' is left alone
350 348
  *               (forced "relative" or "absolute" path). Otherwise the path
351 349
  *               is considered to be relative to the main config file directory
352
- *               (e.g. for /etc/ser/ser.cfg => /etc/ser/<path>).
350
+ *               (e.g. for /etc/ser/ser.cfg => /etc/ser/\<path\>).
353 351
  * @return  0 on success, -1 on error.
354 352
  */
355 353
 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 186
  * Parse SIP message and populate leg informations. 
189 187
  * \param dlg the dialog to add cseq, contact & record_route
190 188
  * \param msg sip message
191
- * \param flag  0-for a request(INVITE), 1- for a reply(200 ok)
189
+ * \param t transaction
190
+ * \param leg type of the call leg
191
+ * \param tag SIP To tag
192 192
  * \return 0 on success, -1 on failure
193 193
  * \note for a request: get record route in normal order, for a reply get
194 194
  * 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 74
  * Parse SIP message and populate leg informations. 
77 75
  * \param dlg the dialog to add cseq, contact & record_route
78 76
  * \param msg sip message
79
- * \param flag  0-for a request(INVITE), 1- for a reply(200 ok)
77
+ * \param t transaction
78
+ * \param leg type of the call leg
79
+ * \param tag SIP To tag
80 80
  * \return 0 on success, -1 on failure
81 81
  * \note for a request: get record route in normal order, for a reply get
82 82
  * 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 383
  * \brief Lookup a dialog in the global list
386 384
  * \param h_entry number of the hash table entry
387 385
  * \param h_id id of the hash table entry
388
- * \return dialog on success, NULL on failure
386
+ * \param del will set to 1 if dialog is deleted
387
+ * \return dialog structure on success, NULL on failure or if not found
389 388
  */
390 389
 struct dlg_cell* lookup_dlg( unsigned int h_entry, unsigned int h_id, unsigned int *del)
391 390
 {
... ...
@@ -432,7 +431,8 @@ not_found:
432 431
  * \param ftag from tag
433 432
  * \param ttag to tag
434 433
  * \param dir direction
435
- * \return dialog structure on success, NULL on failure
434
+ * \param del will set to 1 if dialog is deleted
435
+ * \return dialog structure on success, NULL on failure or if not found
436 436
  */
437 437
 static inline struct dlg_cell* internal_get_dlg(unsigned int h_entry,
438 438
 						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 554
  * \brief Unreference a dialog without locking
554 555
  * \param _dlg dialog
555 556
  * \param _cnt decrement for the reference counter
557
+ * \param _d_entry dialog entry
556 558
  */
557 559
 #define unref_dlg_unsafe(_dlg,_cnt,_d_entry)   \
558 560
 	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 255
  * \brief Lookup a dialog in the global list
258 256
  * \param h_entry number of the hash table entry
259 257
  * \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
258
+ * \param del will set to 1 if dialog is deleted
259
+ * \return dialog structure on success, NULL on failure or if not found
262 260
  */
263 261
 struct dlg_cell* lookup_dlg( unsigned int h_entry, unsigned int h_id, unsigned int *del);
264 262
 
... ...
@@ -352,6 +350,7 @@ struct mi_root * mi_terminate_dlgs(struct mi_root *cmd_tree, void *param );
352 350
 /*!
353 351
  * \brief Check if a dialog structure matches to a SIP message dialog
354 352
  * \param dlg dialog structure
353
+ * \param callid SIP message Call-ID
355 354
  * \param ftag SIP message from tag
356 355
  * \param ttag SIP message to tag
357 356
  * \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 376
 	return 0;
378 377
 }
379 378
 
380
-/** load a sr module.
379
+/**
380
+ * \brief load a sr module
381
+ * 
381 382
  * tries to load the module specified by mod_path.
382 383
  * 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
384
+ *  \<MODS_DIR\>/\<modname\>.so will be tried and if this fails
385
+ *  \<MODS_DIR\>/\<modname\>/\<modname\>.so
385 386
  * If mod_path contain a '/' it is assumed to be the 
386 387
  * path to the module and tried first. If fails and mod_path is not
387 388
  * absolute path (not starting with '/') then will try:
388
- *   <MODS_DIR>/mod_path
389
- * @param modname - path or module name
389
+ * \<MODS_DIR\>/mod_path
390
+ * @param mod_path path or module name
390 391
  * @return 0 on success , <0 on error
391 392
  */
392 393
 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 56
 	return 0;
56 57
 }
57 58
 
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
-  */
59
+/**
60
+ * \brief Forks a separate simple sleep() periodic timer
61
+ * 
62
+ * Forks a very basic periodic timer process, that just sleep()s for 
63
+ * the specified interval and then calls the timer function.
64
+ * The new "dummy timer" process execution start immediately, the sleep()
65
+ * is called first (so the first call to the timer function will happen
66
+ * \<interval\> seconds after the call to fork_dummy_timer)
67
+ * @param child_id  @see fork_process()
68
+ * @param desc      @see fork_process()
69
+ * @param make_sock @see fork_process()
70
+ * @param f         timer function/callback
71
+ * @param param     parameter passed to the timer function
72
+ * @param interval  interval in seconds.
73
+ * @return pid of the new process on success, -1 on error
74
+ * (doesn't return anything in the child process)
75
+ */
73 76
 int fork_dummy_timer(int child_id, char* desc, int make_sock,
74 77
 						timer_function* f, void* param, int interval)
75 78
 {
... ...
@@ -93,31 +96,33 @@ int fork_dummy_timer(int child_id, char* desc, int make_sock,
93 96
 
94 97
 
95 98
 
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){
99
+/**
100
+ * \brief Forks a timer process based on the local timer
101
+ * 
102
+ * Forks a separate timer process running a local_timer.h type of timer
103
+ * A pointer to the local_timer handle (allocated in shared memory) is
104
+ * returned in lt_h. It can be used to add/delete more timers at runtime
105
+ * (via local_timer_add()/local_timer_del() a.s.o).
106
+ * If timers are added from separate processes, some form of locking must be
107
+ * used (all the calls to local_timer* must be enclosed by locks if it
108
+ * cannot be guaranteed that they cannot execute in the same time)
109
+ * The timer "engine" must be run manually from the child process. For
110
+ * example a very simple local timer process that just runs a single 
111
+ * periodic timer can be started in the following way:
112
+ * struct local_timer* lt_h;
113
+ * 
114
+ * pid=fork_local_timer_process(...., &lt_h);
115
+ * if (pid==0){
111 116
  *          timer_init(&my_timer, my_timer_f, 0, 0);
112 117
  *          local_timer_add(&lt_h, &my_timer, S_TO_TICKS(10), get_ticks_raw());
113 118
  *          while(1) { sleep(1); local_timer_run(lt, get_ticks_raw()); }
114
- *      }
119
+ * }
115 120
  *
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.
121
+ * @param child_id  @see fork_process()
122
+ * @param desc      @see fork_process()
123
+ * @param make_sock @see fork_process()
124
+ * @param lt_h      local_timer handler
125
+ * @return pid to the parent, 0 to the child, -1 if error.
121 126
  */
122 127
 int fork_local_timer_process(int child_id, char* desc, int make_sock,
123 128
 						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 34
 
37 35
 #include "local_timer.h"
38 36
 
39
-/** @brief register the number of extra dummy timer processes */
37
+/**
38
+ * \brief update internal counters for running new dummy timers
39
+ * @param timers number of dummy timer processes
40
+ * @return 0 on success; -1 on error
41
+ */
40 42
 int register_dummy_timers(int timers);
41 43
 
42
-/** @brief forks a separate simple sleep() periodic timer */
44
+
45
+/**
46
+ * \brief Forks a separate simple sleep() periodic timer
47
+ * 
48
+ * Forks a very basic periodic timer process, that just sleep()s for 
49
+ * the specified interval and then calls the timer function.
50
+ * The new "dummy timer" process execution start immediately, the sleep()
51
+ * is called first (so the first call to the timer function will happen
52
+ * \<interval\> seconds after the call to fork_dummy_timer)
53
+ * @param child_id  @see fork_process()
54
+ * @param desc      @see fork_process()
55
+ * @param make_sock @see fork_process()
56
+ * @param f         timer function/callback
57
+ * @param param     parameter passed to the timer function
58
+ * @param interval  interval in seconds.
59
+ * @return pid of the new process on success, -1 on error
60
+ * (doesn't return anything in the child process)
61
+ */
43 62
 int fork_dummy_timer(int child_id, char* desc, int make_sock,
44 63
 						timer_function* f, void* param, int interval);
45 64
 
46
-/** @briefforks a timer process based on the local timer */
65
+
66
+/**
67
+ * \brief Forks a timer process based on the local timer
68
+ * 
69
+ * Forks a separate timer process running a local_timer.h type of timer
70
+ * A pointer to the local_timer handle (allocated in shared memory) is
71
+ * returned in lt_h. It can be used to add/delete more timers at runtime
72
+ * (via local_timer_add()/local_timer_del() a.s.o).
73
+ * If timers are added from separate processes, some form of locking must be
74
+ * used (all the calls to local_timer* must be enclosed by locks if it
75
+ * cannot be guaranteed that they cannot execute in the same time)
76
+ * The timer "engine" must be run manually from the child process. For
77
+ * example a very simple local timer process that just runs a single 
78
+ * periodic timer can be started in the following way:
79
+ * struct local_timer* lt_h;
80
+ * 
81
+ * pid=fork_local_timer_process(...., &lt_h);
82
+ * if (pid==0){
83
+ *          timer_init(&my_timer, my_timer_f, 0, 0);
84
+ *          local_timer_add(&lt_h, &my_timer, S_TO_TICKS(10), get_ticks_raw());
85
+ *          while(1) { sleep(1); local_timer_run(lt, get_ticks_raw()); }
86
+ * }
87
+ *
88
+ * @param child_id  @see fork_process()
89
+ * @param desc      @see fork_process()
90
+ * @param make_sock @see fork_process()
91
+ * @param lt_h      local_timer handler
92
+ * @return pid to the parent, 0 to the child, -1 if error.
93
+ */
47 94
 int fork_local_timer_process(int child_id, char* desc, int make_sock,
48 95
 						struct local_timer** lt_h);
49 96
 
... ...
@@ -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 858
  *       - "<track><class>.<name>[<index>]"      (e.g:  fd.bar[2])
861 859
  *       - "<string>"                            (e.g.: foo)
862 860
  * Where:
863
- *          <string> = ascii string
864
- *          <id>   = ascii string w/o '[', ']', '.' and '/'
865
- *          <name> = <id> | '/' regex '/'
861
+ *          \<string\> = ascii string
862
+ *          \<id\>   = ascii string w/o '[', ']', '.' and '/'
863
+ *          \<name\> = \<id\> | '/' regex '/'
866 864
  *                   (Note: regex use is deprecated)
867
- *          <track> = 'f' | 't'
865
+ *          \<track\> = 'f' | 't'
868 866
  *                   (from or to)
869
- *          <class> = 'r' | 'u' | 'd' | 'g'
867
+ *          \<class\> = 'r' | 'u' | 'd' | 'g'
870 868
  *                    (uri, user, domain or global)
871
- *          <index> = <number> | '-' <number> | ''
869
+ *          \<index\> = \<number\> | '-' \<number\> | ''
872 870
  *                    (the avp index, if missing it means AVP_INDEX_ALL, but
873 871
  *                     it's use is deprecated)
874 872
  * More examples: