Browse code

core: fix all reported doxygen errors in PV and value evaluation code

Henning Westerholt authored on 28/07/2011 21:58:00
Showing 4 changed files
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2008 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -15,10 +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
  */
16
+
18 17
 /**
19 18
  * @file 
20
- * @brief lvalues (assignment)
19
+ * @brief SIP-router core :: lvalues (assignment)
20
+ * \ingroup core
21
+ * Module: \ref core
21 22
  */
23
+
22 24
 /* 
23 25
  * History:
24 26
  * --------
... ...
@@ -29,12 +31,6 @@
29 31
  *              delete the lvalue (similar to perl)  (andrei)
30 32
  */
31 33
 
32
-/*!
33
- * \file
34
- * \brief SIP-router core :: 
35
- * \ingroup core
36
- * Module: \ref core
37
- */
38 34
 
39 35
 #include "lvalue.h"
40 36
 #include "dprint.h"
... ...
@@ -42,15 +38,15 @@
42 38
 
43 39
 
44 40
 
45
-/** eval rve and assign the result to an avp
46
- * lv->lv.avp=eval(rve)
47
- *
48
- * based on do_action() ASSIGN_T
49
- *
41
+/**
42
+ * @brief eval rve and assign the result to an avp
43
+ * 
44
+ * eval rve and assign the result to an avp, lv->lv.avp=eval(rve)
45
+ * based on do_action() ASSIGN_T.
50 46
  * @param h  - script context
51 47
  * @param msg - sip msg
52 48
  * @param lv - lvalue
53
- * @param rve - rvalue expression
49
+ * @param rv - rvalue expression
54 50
  * @return >= 0 on success (expr. bool value), -1 on error
55 51
  */
56 52
 inline static int lval_avp_assign(struct run_act_ctx* h, struct sip_msg* msg,
... ...
@@ -232,15 +228,15 @@ drop:
232 228
 
233 229
 
234 230
 
235
-/** eval rve and assign the result to a pvar
236
- * lv->lv.pvar=eval(rve)
237
- *
238
- * based on do_action() ASSIGN_T
231
+/**
232
+ * @brief eval rve and assign the result to a pvar
239 233
  *
234
+ * eval rve and assign the result to a pvar, lv->lv.pvar=eval(rve)
235
+ * based on do_action() ASSIGN_T.
240 236
  * @param h  - script context
241 237
  * @param msg - sip msg
242 238
  * @param lv - lvalue
243
- * @param rve - rvalue expression
239
+ * @param rv - rvalue expression
244 240
  * @return >= 0 on success (expr. bool value), -1 on error
245 241
  */
246 242
 inline static int lval_pvar_assign(struct run_act_ctx* h, struct sip_msg* msg,
... ...
@@ -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 SIP-Router, a free SIP server.
... ...
@@ -22,7 +20,7 @@
22 20
 
23 21
 /*!
24 22
  * \file
25
- * \brief SIP-router core ::  PV API specification
23
+ * \brief SIP-router core :: PV API specification
26 24
  * \ingroup core
27 25
  * Module: \ref core
28 26
  */
... ...
@@ -44,8 +42,8 @@
44 42
 
45 43
 #define is_in_str(p, in) (p<in->s+in->len && *p)
46 44
 
47
-#define PV_TABLE_SIZE	16
48
-#define TR_TABLE_SIZE	4
45
+#define PV_TABLE_SIZE	16 /*!< pseudo-variable table size */
46
+#define TR_TABLE_SIZE	4  /*!< PV transformation size */
49 47
 
50 48
 
51 49
 void tr_destroy(trans_t *t);
... ...
@@ -72,7 +70,9 @@ void pv_init_table(void)
72 70
 }
73 71
 
74 72
 /**
75
- *
73
+ * @brief Check if a char is valid according to the PV syntax
74
+ * @param c checked char
75
+ * @return 1 if char is valid, 0 if not valid
76 76
  */
77 77
 static int is_pv_valid_char(char c)
78 78
 {
... ...
@@ -1335,11 +1335,10 @@ void tr_destroy(trans_t *t)
1335 1335
 /*!
1336 1336
  * \brief Exec transformation on a pseudo-variable value
1337 1337
  * \param msg SIP message
1338
- * \param tr one or more transformations
1339
- * \param val pseudo-variable value
1338
+ * \param t one or more transformations
1339
+ * \param v pseudo-variable value
1340 1340
  * \return 0 on success, -1 on error
1341 1341
  */
1342
-
1343 1342
 int tr_exec(struct sip_msg *msg, trans_t *t, pv_value_t *v)
1344 1343
 {
1345 1344
 	int r;
... ...
@@ -1,6 +1,4 @@
1 1
 /* 
2
- * $Id$
3
- * 
4 2
  * Copyright (C) 2008 iptelorg GmbH
5 3
  *
6 4
  * Permission to use, copy, modify, and distribute this software for any
... ...
@@ -15,10 +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
  */
16
+
18 17
 /**
19 18
  * @file 
20
- * @brief rvalue expressions
19
+ * @brief SIP-router core :: rvalue expressions
20
+ * @ingroup core
21
+ * Module: \ref core
21 22
  */
23
+
22 24
 /* 
23 25
  * History:
24 26
  * --------
... ...
@@ -58,12 +60,6 @@
58 60
  *                           Depends on RV_STR2INT_ERR.
59 61
  */
60 62
 
61
-/*!
62
- * \file
63
- * \brief SIP-router core :: 
64
- * \ingroup core
65
- * Module: \ref core
66
- */
67 63
 
68 64
 #include "rvalue.h"
69 65
 
... ...
@@ -344,14 +340,14 @@ char* rval_type_name(enum rval_type type)
344 340
 
345 341
 
346 342
 
347
-/** create a new pk_malloc'ed rvalue from a rval_val union.
348
-  *
349
-  * @param s - pointer to str, must be non-null
350
-  * @param extra_size - extra space to allocate
351
-  *                    (so that future string operation can reuse
352
-  *                     the space)
353
-  * @return new rv or 0 on error
354
-  */
343
+/**
344
+ * @brief create a new pk_malloc'ed rvalue from a rval_val union
345
+ * @param t rvalue type
346
+ * @param v rvalue value
347
+ * @param extra_size extra space to allocate
348
+ * (so that future string operation can reuse the space)
349
+ * @return new rv or 0 on error
350
+ */
355 351
 struct rvalue* rval_new(enum rval_type t, union rval_val* v, int extra_size)
356 352
 {
357 353
 	struct rvalue* rv;
... ...
@@ -375,18 +371,21 @@ struct rvalue* rval_new(enum rval_type t, union rval_val* v, int extra_size)
375 371
 
376 372
 
377 373
 
378
-/** get rvalue basic type (RV_INT or RV_STR).
379
-  *
380
-  * Given a rvalue it tries to determinte its basic type.
381
-  * Fills val_cache if non-null and empty (can be used in other rval*
382
-  * function calls, to avoid re-resolving avps or pvars). It must be
383
-  * rval_cache_clean()'en when no longer needed.
384
-  *
385
-  * @param rv - target rvalue
386
-  * @param val_cache - write-only: value cache, might be filled if non-null,
387
-  *                    it _must_ be rval_cache_clean()'en when done.
388
-  * @return - basic type or RV_NONE on error
389
-  */
374
+/**
375
+ * @brief get rvalue basic type (RV_INT or RV_STR)
376
+ *
377
+ * Given a rvalue it tries to determinte its basic type.
378
+ * Fills val_cache if non-null and empty (can be used in other rval*
379
+ * function calls, to avoid re-resolving avps or pvars). It must be
380
+ * rval_cache_clean()'en when no longer needed.
381
+ *
382
+ * @param h run action context
383
+ * @param msg SIP message
384
+ * @param rv target rvalue
385
+ * @param val_cache write-only value cache, might be filled if non-null,
386
+ * it _must_ be rval_cache_clean()'en when done.
387
+ * @return basic type or RV_NONE on error
388
+ */
390 389
 inline static enum rval_type rval_get_btype(struct run_act_ctx* h,
391 390
 											struct sip_msg* msg,
392 391
 											struct rvalue* rv,
... ...
@@ -675,18 +674,19 @@ static int rve_op_unary(enum rval_expr_op op)
675 674
 
676 675
 
677 676
 
678
-/** returns 1 if expression is valid (type-wise).
679
-  * @param type - filled with the type of the expression (RV_INT, RV_STR or
680
-  *                RV_NONE if it's dynamic)
681
-  * @param rve  - checked expression
682
-  * @param bad_rve - set on failure to the subexpression for which the 
683
-  *                    type check failed
684
-  * @param bad_type - set on failure to the type of the bad subexpression
685
-  * @param exp_type - set on failure to the expected type for the bad
686
-  *                   subexpression
687
-  * @return 0 or 1  and sets *type to the resulting type
688
-  * (RV_INT, RV_STR or RV_NONE if it can be found only at runtime)
689
-  */
677
+/**
678
+ * @brief Returns 1 if expression is valid (type-wise)
679
+ * @param type filled with the type of the expression (RV_INT, RV_STR or
680
+ *                RV_NONE if it's dynamic)
681
+ * @param rve  checked expression
682
+ * @param bad_rve set on failure to the subexpression for which the 
683
+ * type check failed
684
+ * @param bad_t set on failure to the type of the bad subexpression
685
+ * @param exp_t set on failure to the expected type for the bad
686
+ * subexpression
687
+ * @return 0 or 1 and sets *type to the resulting type
688
+ * (RV_INT, RV_STR or RV_NONE if it can be found only at runtime)
689
+ */
690 690
 int rve_check_type(enum rval_type* type, struct rval_expr* rve,
691 691
 					struct rval_expr** bad_rve, 
692 692
 					enum rval_type* bad_t,
... ...
@@ -1274,18 +1274,22 @@ error:
1274 1274
 
1275 1275
 
1276 1276
 
1277
-/** convert a rvalue to another rvalue, of a specific type.
1277
+/**
1278
+ * @brief Convert a rvalue to another rvalue, of a specific type
1278 1279
  *
1280
+ * Convert a rvalue to another rvalue, of a specific type.
1279 1281
  * The result is read-only in most cases (can be a reference
1280 1282
  * to another rvalue, can be checked by using rv_chg_in_place()) and
1281 1283
  * _must_ be rval_destroy()'ed.
1282 1284
  *
1285
+ * @param h run action context
1286
+ * @param msg SIP mesasge
1283 1287
  * @param type - type to convert to
1284 1288
  * @param v - rvalue to convert
1285 1289
  * @param c - rval_cache (cached v value if known/filled by another
1286 1290
  *            function), can be 0 (unknown/not needed)
1287 1291
  * @return pointer to a rvalue (reference to an existing one or a new
1288
- *   one, @see rv_chg_in_place() and the above comment) or 0 on error.
1292
+ * one, @see rv_chg_in_place() and the above comment), or 0 on error.
1289 1293
  */
1290 1294
 struct rvalue* rval_convert(struct run_act_ctx* h, struct sip_msg* msg,
1291 1295
 							enum rval_type type, struct rvalue* v,
... ...
@@ -1761,9 +1765,17 @@ error:
1761 1765
 
1762 1766
 
1763 1767
 
1764
-/** integer operation on rval evaluated as string.
1765
- * Can use cached rvalues (c1 & c2).
1766
- * @param res - will be set to the result
1768
+/**
1769
+ * @brief Integer operation on rval evaluated as string
1770
+ * 
1771
+ * Integer operation on rval evaluated as string, can use cached
1772
+ * rvalues (c1 & c2).
1773
+ * @param h run action context
1774
+ * @param msg SIP message
1775
+ * @param res will be set to the result
1776
+ * @param op rvalue expression operation
1777
+ * @param l rvalue
1778
+ * @param c1 rvalue cache
1767 1779
  * @return 0 success, -1 on error
1768 1780
  */
1769 1781
 inline static int rval_int_strop1(struct run_act_ctx* h,
... ...
@@ -1791,14 +1803,18 @@ error:
1791 1803
 
1792 1804
 
1793 1805
 
1794
-/** checks if rv is defined.
1795
- * @param res - set to the result 1 - defined, 0 not defined
1806
+/**
1807
+ * @brief Checks if rv is defined
1808
+ * @param h run action context
1809
+ * @param msg SIP message
1810
+ * @param res set to the result 1 is defined, 0 not defined
1811
+ * @param rv rvalue
1812
+ * @param cache rvalue cache
1796 1813
  * @return 0 on success, -1 on error
1797
- * Can use cached rvalues (cache).
1798
- * Note: a rv can be undefined if it's an undefined avp or pvar or select or
1799
- * if it's NONE
1800
- * Note2: an error in the avp, pvar or select search is equivalent to 
1801
- *  undefined (and it's not reported)
1814
+ * @note Can use cached rvalues (cache). A rv can be undefined if it's
1815
+ * an undefined avp or pvar or select or if it's NONE
1816
+ * @note An error in the avp, pvar or select search is equivalent to
1817
+ * undefined (and it's not reported)
1802 1818
  */
1803 1819
 inline static int rv_defined(struct run_act_ctx* h,
1804 1820
 						 struct sip_msg* msg, int* res,
... ...
@@ -1857,9 +1873,13 @@ inline static int rv_defined(struct run_act_ctx* h,
1857 1873
 }
1858 1874
 
1859 1875
 
1860
-/** defined (integer) operation on rve.
1876
+/**
1877
+ * @brief Defined (integer) operation on rve
1878
+ * @param h run action context
1879
+ * @param msg SIP message
1861 1880
  * @param res - set to  1 defined, 0 not defined
1862
- * @return - 0 on success, -1 on error
1881
+ * @param rve rvalue expression
1882
+ * @return 0 on success, -1 on error
1863 1883
  */
1864 1884
 inline static int int_rve_defined(struct run_act_ctx* h,
1865 1885
 						 struct sip_msg* msg, int* res,
... ...
@@ -2129,22 +2149,22 @@ int rval_expr_eval_int( struct run_act_ctx* h, struct sip_msg* msg,
2129 2149
 
2130 2150
 
2131 2151
 
2132
-/** evals a rval expr. into an int or another rv(str).
2133
- * WARNING: rv result (rv_res) must be rval_destroy()'ed if non-null
2152
+/**
2153
+ * @brief Evals a rval expression into an int or another rv(str)
2154
+ * @warning rv result (rv_res) must be rval_destroy()'ed if non-null
2134 2155
  * (it might be a reference to another rval). The result can be
2135 2156
  * modified only if rv_chg_in_place() returns true.
2136
- * @param res_rv - pointer to rvalue result, if non-null it means the 
2137
- *                 expression evaluated to a non-int (str), which will be
2138
- *                 stored here.
2139
- * @param res_i  - pointer to int result, if res_rv==0 and the function
2140
- *                 returns success => the result is an int which will be 
2141
- *                 stored here.
2142
- * @param rve    - expression that will be evaluated.
2143
- * @param cache  - write-only value cache, it might be filled if non-null and
2144
- *                 empty (rval_cache_init()). If non-null, it _must_ be 
2145
- *                 rval_cache_clean()'ed when done. 
2146
- *
2147
- * @result  0 on success, -1 on error,  sets *res_rv or *res_i.
2157
+ * @param h run action context
2158
+ * @param msg SIP message
2159
+ * @param res_rv pointer to rvalue result, if non-null it means the 
2160
+ * expression evaluated to a non-int (str), which will be stored here.
2161
+ * @param res_i pointer to int result, if res_rv==0 and the function
2162
+ * returns success => the result is an int which will be stored here.
2163
+ * @param rve expression that will be evaluated.
2164
+ * @param cache write-only value cache, it might be filled if non-null and
2165
+ * empty (rval_cache_init()). If non-null, it _must_ be rval_cache_clean()'ed
2166
+ * when done. 
2167
+ * @return 0 on success, -1 on error, sets *res_rv or *res_i.
2148 2168
  */
2149 2169
 int rval_expr_eval_rvint(			   struct run_act_ctx* h,
2150 2170
 									   struct sip_msg* msg,
... ...
@@ -2281,10 +2301,14 @@ error:
2281 2301
 
2282 2302
 
2283 2303
 
2284
-/** evals a rval expr..
2285
- * WARNING: result must be rval_destroy()'ed if non-null (it might be
2304
+/**
2305
+ * @brief Evals a rval expression
2306
+ * @warning result must be rval_destroy()'ed if non-null (it might be
2286 2307
  * a reference to another rval). The result can be modified only
2287 2308
  * if rv_chg_in_place() returns true.
2309
+ * @param h run action context
2310
+ * @param msg SIP message
2311
+ * @param rve rvalue expression
2288 2312
  * @return rvalue on success, 0 on error
2289 2313
  */
2290 2314
 struct rvalue* rval_expr_eval(struct run_act_ctx* h, struct sip_msg* msg,
... ...
@@ -2556,10 +2580,12 @@ struct rval_expr* mk_rval_expr_v(enum rval_type rv_type, void* val,
2556 2580
 
2557 2581
 
2558 2582
 
2559
-/** create a unary op. rval_expr..
2583
+/**
2584
+ * @brief Create a unary op. rval_expr
2560 2585
  * ret= op rve1
2561 2586
  * @param op   - rval expr. unary operator
2562 2587
  * @param rve1 - rval expr. on which the operator will act.
2588
+ * @param pos configuration position
2563 2589
  * @return new pkg_malloc'ed rval_expr or 0 on error.
2564 2590
  */
2565 2591
 struct rval_expr* mk_rval_expr1(enum rval_expr_op op, struct rval_expr* rve1,
... ...
@@ -2594,11 +2620,13 @@ struct rval_expr* mk_rval_expr1(enum rval_expr_op op, struct rval_expr* rve1,
2594 2620
 
2595 2621
 
2596 2622
 
2597
-/** create a rval_expr. from 2 other rval exprs, using op.
2623
+/**
2624
+ * @brief Create a rval_expr. from 2 other rval exprs, using op
2598 2625
  * ret = rve1 op rve2
2599 2626
  * @param op   - rval expr. operator
2600 2627
  * @param rve1 - rval expr. on which the operator will act.
2601 2628
  * @param rve2 - rval expr. on which the operator will act.
2629
+ * @param pos configuration position
2602 2630
  * @return new pkg_malloc'ed rval_expr or 0 on error.
2603 2631
  */
2604 2632
 struct rval_expr* mk_rval_expr2(enum rval_expr_op op, struct rval_expr* rve1,
... ...
@@ -2862,15 +2890,17 @@ static int fix_rval(struct rvalue* rv)
2862 2890
 
2863 2891
 
2864 2892
 
2865
-/** helper function: replace a rve (in-place) with a constant rval_val.
2866
- * WARNING: since it replaces in-place, one should make sure that if
2893
+/**
2894
+ * @brief Helper function: replace a rve (in-place) with a constant rval_val
2895
+ * @warning since it replaces in-place, one should make sure that if
2867 2896
  * rve is in fact a rval (rve->op==RVE_RVAL_OP), no reference is kept
2868 2897
  * to the rval!
2869
- * @param rve - expression to be replaced (in-place)
2870
- * @param v   - pointer to a rval_val union containing the replacement
2871
- *              value.
2872
- * @param flags - value flags (how it was alloc'ed, e.g.: RV_CNT_ALLOCED_F)
2873
- * @return 0 on success, -1 on error */
2898
+ * @param rve expression to be replaced (in-place)
2899
+ * @param type rvalue type
2900
+ * @param v pointer to a rval_val union containing the replacement value.
2901
+ * @param flags value flags (how it was alloc'ed, e.g.: RV_CNT_ALLOCED_F)
2902
+ * @return 0 on success, -1 on error
2903
+ */
2874 2904
 static int rve_replace_with_val(struct rval_expr* rve, enum rval_type type,
2875 2905
 								union rval_val* v, int flags)
2876 2906
 {
... ...
@@ -16,7 +16,9 @@
16 16
  
17 17
 /**
18 18
  * @file 
19
- * @brief rvalue expressions
19
+ * @brief SIP-router core :: rvalue expressions
20
+ * @ingroup core
21
+ * Module: \ref core
20 22
  */
21 23
  
22 24
 /* 
... ...
@@ -48,45 +50,45 @@ enum rval_type{
48 50
 };
49 51
 
50 52
 enum rval_expr_op{
51
-	RVE_NONE_OP,  /* uninit / empty */
52
-	RVE_RVAL_OP,  /* special op, means that the expr. is in fact a rval */
53
-	RVE_UMINUS_OP, /* one member expression, returns -(val) */
54
-	RVE_BOOL_OP,  /* one member evaluate as bool. : (val!=0)*/
55
-	RVE_LNOT_OP,  /* one member evaluate as bool. : (!val)*/
56
-	RVE_BNOT_OP,  /* one member evaluate as binary : (~ val)*/
57
-	RVE_MUL_OP,   /* 2 members, returns left * right */
58
-	RVE_DIV_OP,   /* 2 members, returns left / right */
59
-	RVE_MOD_OP,   /* 2 members, returns left % right */
60
-	RVE_MINUS_OP, /* 2 members, returns left - right */
61
-	RVE_BAND_OP,  /* 2 members, returns left | right */
62
-	RVE_BOR_OP,   /* 2 members, returns left & right */
63
-	RVE_BXOR_OP,   /* 2 members, returns left XOR right */
64
-	RVE_BLSHIFT_OP,   /* 2 members, returns left << right */
65
-	RVE_BRSHIFT_OP,   /* 2 members, returns left >> right */
66
-	RVE_LAND_OP,  /* 2 members, returns left && right */
67
-	RVE_LOR_OP,   /* 2 members, returns left || right */
68
-	RVE_GT_OP,    /*  2 members, returns left > right */
69
-	RVE_GTE_OP,   /*  2 members, returns left >= right */
70
-	RVE_LT_OP,    /*  2 members, returns left  < right */
71
-	RVE_LTE_OP,   /*  2 members, returns left <= right */
72
-	RVE_IEQ_OP, /*  2 members, int == version, returns left == right */
73
-	RVE_IDIFF_OP,/* 2 members, int != version, returns left != right */
74
-	RVE_IPLUS_OP, /* 2 members, integer +, returns int(a)+int(b) */
53
+	RVE_NONE_OP,  /**< uninit / empty */
54
+	RVE_RVAL_OP,  /**< special op, means that the expr. is in fact a rval */
55
+	RVE_UMINUS_OP, /**< one member expression, returns -(val) */
56
+	RVE_BOOL_OP,  /**< one member evaluate as bool. : (val!=0)*/
57
+	RVE_LNOT_OP,  /**< one member evaluate as bool. : (!val)*/
58
+	RVE_BNOT_OP,  /**< one member evaluate as binary : (~ val)*/
59
+	RVE_MUL_OP,   /**< 2 members, returns left * right */
60
+	RVE_DIV_OP,   /**< 2 members, returns left / right */
61
+	RVE_MOD_OP,   /**< 2 members, returns left % right */
62
+	RVE_MINUS_OP, /**< 2 members, returns left - right */
63
+	RVE_BAND_OP,  /**< 2 members, returns left | right */
64
+	RVE_BOR_OP,   /**< 2 members, returns left & right */
65
+	RVE_BXOR_OP,   /**< 2 members, returns left XOR right */
66
+	RVE_BLSHIFT_OP, /**< 2 members, returns left << right */
67
+	RVE_BRSHIFT_OP, /**< 2 members, returns left >> right */
68
+	RVE_LAND_OP,  /**< 2 members, returns left && right */
69
+	RVE_LOR_OP,   /**< 2 members, returns left || right */
70
+	RVE_GT_OP,    /**<  2 members, returns left > right */
71
+	RVE_GTE_OP,   /**<  2 members, returns left >= right */
72
+	RVE_LT_OP,    /**<  2 members, returns left  < right */
73
+	RVE_LTE_OP,   /**<  2 members, returns left <= right */
74
+	RVE_IEQ_OP,   /**<  2 members, int == version, returns left == right */
75
+	RVE_IDIFF_OP, /**< 2 members, int != version, returns left != right */
76
+	RVE_IPLUS_OP, /**< 2 members, integer +, returns int(a)+int(b) */
75 77
 	/* common int & str */
76
-	RVE_PLUS_OP,  /* generic plus (int or str) returns left + right */
77
-	RVE_EQ_OP,    /*  2 members, returns left == right  (int)*/
78
-	RVE_DIFF_OP,  /*  2 members, returns left != right  (int)*/
78
+	RVE_PLUS_OP,  /**< generic plus (int or str) returns left + right */
79
+	RVE_EQ_OP,    /**<  2 members, returns left == right  (int)*/
80
+	RVE_DIFF_OP,  /**<  2 members, returns left != right  (int)*/
79 81
 	/* str only */
80
-	RVE_CONCAT_OP,/* 2 members, string concat, returns left . right (str)*/
81
-	RVE_STRLEN_OP, /* one member, string length:, returns strlen(val) (int)*/
82
-	RVE_STREMPTY_OP, /* one member, returns val=="" (bool) */
83
-	RVE_STREQ_OP,  /* 2 members, string == , returns left == right (bool)*/
84
-	RVE_STRDIFF_OP,/* 2 members, string != , returns left != right (bool)*/
85
-	RVE_MATCH_OP,  /* 2 members, string ~),  returns left matches re(right) */
82
+	RVE_CONCAT_OP, /**< 2 members, string concat, returns left . right (str)*/
83
+	RVE_STRLEN_OP, /**< one member, string length:, returns strlen(val) (int)*/
84
+	RVE_STREMPTY_OP, /**< one member, returns val=="" (bool) */
85
+	RVE_STREQ_OP,  /**< 2 members, string == , returns left == right (bool)*/
86
+	RVE_STRDIFF_OP,/**< 2 members, string != , returns left != right (bool)*/
87
+	RVE_MATCH_OP,  /**< 2 members, string ~),  returns left matches re(right) */
86 88
 	/* avp, pvars a.s.o */
87
-	RVE_DEFINED_OP, /* one member, returns is_defined(val) (bool) */
88
-	RVE_INT_OP,   /* one member, returns (int)val  (int) */
89
-	RVE_STR_OP    /* one member, returns (str)val  (str) */
89
+	RVE_DEFINED_OP, /**< one member, returns is_defined(val) (bool) */
90
+	RVE_INT_OP,   /**< one member, returns (int)val  (int) */
91
+	RVE_STR_OP    /**< one member, returns (str)val  (str) */
90 92
 };
91 93
 
92 94
 
... ...
@@ -119,12 +121,11 @@ struct rvalue{
119 121
 
120 122
 
121 123
 /* rvalue flags */
122
-#define RV_CNT_ALLOCED_F  1  /* free contents  (pkg mem allocated) */
123
-#define RV_RV_ALLOCED_F   2  /* free rv itself (pkg_free(rv)) */
124
+#define RV_CNT_ALLOCED_F  1  /**< free contents  (pkg mem allocated) */
125
+#define RV_RV_ALLOCED_F   2  /**< free rv itself (pkg_free(rv)) */
124 126
 #define RV_ALL_ALLOCED_F  (RV_CNT_ALLOCED|RV_RV_ALLOCED)
125
-#define RV_RE_F  4 /* string is a RE with a valid v->re member */
126
-#define RV_RE_ALLOCED_F 8 /* v->re.regex must be freed */
127
-
127
+#define RV_RE_F  4 /**< string is a RE with a valid v->re member */
128
+#define RV_RE_ALLOCED_F 8 /**< v->re.regex must be freed */
128 129
 
129 130
 struct rval_expr{
130 131
 	enum rval_expr_op op;
... ...
@@ -167,6 +168,15 @@ struct rval_cache{
167 168
 /** allocates a new rval (should be freed by rval_destroy()). */
168 169
 struct rvalue* rval_new_empty(int extra_size);
169 170
 struct rvalue* rval_new_str(str* s, int extra_size);
171
+
172
+/**
173
+ * @brief create a new pk_malloc'ed rvalue from a rval_val union
174
+ * @param t rvalue type
175
+ * @param v rvalue value
176
+ * @param extra_size extra space to allocate
177
+ * (so that future string operation can reuse the space)
178
+ * @return new rv or 0 on error
179
+ */
170 180
 struct rvalue* rval_new(enum rval_type t, union rval_val* v, int extra_size);
171 181
 
172 182
 /** inits a rvalue structure- */
... ...
@@ -186,7 +196,23 @@ void rval_clean(struct rvalue* rv);
186 196
 void rval_cache_clean(struct rval_cache* rvc);
187 197
 
188 198
 
189
-/** convert a rvalue to another type.  */
199
+/**
200
+ * @brief Convert a rvalue to another rvalue, of a specific type
201
+ *
202
+ * Convert a rvalue to another rvalue, of a specific type.
203
+ * The result is read-only in most cases (can be a reference
204
+ * to another rvalue, can be checked by using rv_chg_in_place()) and
205
+ * _must_ be rval_destroy()'ed.
206
+ *
207
+ * @param h run action context
208
+ * @param msg SIP mesasge
209
+ * @param type - type to convert to
210
+ * @param v - rvalue to convert
211
+ * @param c - rval_cache (cached v value if known/filled by another
212
+ *            function), can be 0 (unknown/not needed)
213
+ * @return pointer to a rvalue (reference to an existing one or a new
214
+ * one, @see rv_chg_in_place() and the above comment), or 0 on error.
215
+ */
190 216
 struct rvalue* rval_convert(struct run_act_ctx* h, struct sip_msg* msg, 
191 217
 							enum rval_type type, struct rvalue* v,
192 218
 							struct rval_cache* c);
... ...
@@ -207,10 +233,37 @@ int rval_get_tmp_str(struct run_act_ctx* h, struct sip_msg* msg,
207 233
 /** evals an integer expr  to an int. */
208 234
 int rval_expr_eval_int( struct run_act_ctx* h, struct sip_msg* msg,
209 235
 						int* res, struct rval_expr* rve);
210
-/** evals a rval expr.. */
236
+
237
+/**
238
+ * @brief Evals a rval expression
239
+ * @warning result must be rval_destroy()'ed if non-null (it might be
240
+ * a reference to another rval). The result can be modified only
241
+ * if rv_chg_in_place() returns true.
242
+ * @param h run action context
243
+ * @param msg SIP message
244
+ * @param rve rvalue expression
245
+ * @return rvalue on success, 0 on error
246
+ */
211 247
 struct rvalue* rval_expr_eval(struct run_act_ctx* h, struct sip_msg* msg,
212 248
 								struct rval_expr* rve);
213
-/** evals an integer expr  to an int or rvalue. */
249
+
250
+/**
251
+ * @brief Evals a rval expression into an int or another rv(str)
252
+ * @warning rv result (rv_res) must be rval_destroy()'ed if non-null
253
+ * (it might be a reference to another rval). The result can be
254
+ * modified only if rv_chg_in_place() returns true.
255
+ * @param h run action context
256
+ * @param msg SIP message
257
+ * @param res_rv pointer to rvalue result, if non-null it means the 
258
+ * expression evaluated to a non-int (str), which will be stored here.
259
+ * @param res_i pointer to int result, if res_rv==0 and the function
260
+ * returns success => the result is an int which will be stored here.
261
+ * @param rve expression that will be evaluated.
262
+ * @param cache write-only value cache, it might be filled if non-null and
263
+ * empty (rval_cache_init()). If non-null, it _must_ be rval_cache_clean()'ed
264
+ * when done. 
265
+ * @return 0 on success, -1 on error, sets *res_rv or *res_i.
266
+ */
214 267
 int rval_expr_eval_rvint( struct run_act_ctx* h, struct sip_msg* msg,
215 268
 						 struct rvalue** rv_res, int* i_res,
216 269
 						 struct rval_expr* rve, struct rval_cache* cache);
... ...
@@ -222,7 +275,20 @@ enum rval_type rve_guess_type(struct rval_expr* rve);
222 275
 int rve_is_constant(struct rval_expr* rve);
223 276
 /** returns true if the expression can have side-effect */
224 277
 int rve_has_side_effects(struct rval_expr* rve);
225
-/** returns 1 if expression is valid (type-wise).*/
278
+
279
+/**
280
+ * @brief Returns 1 if expression is valid (type-wise)
281
+ * @param type filled with the type of the expression (RV_INT, RV_STR or
282
+ *                RV_NONE if it's dynamic)
283
+ * @param rve  checked expression
284
+ * @param bad_rve set on failure to the subexpression for which the 
285
+ * type check failed
286
+ * @param bad_t set on failure to the type of the bad subexpression
287
+ * @param exp_t set on failure to the expected type for the bad
288
+ * subexpression
289
+ * @return 0 or 1 and sets *type to the resulting type
290
+ * (RV_INT, RV_STR or RV_NONE if it can be found only at runtime)
291
+ */
226 292
 int rve_check_type(enum rval_type* type, struct rval_expr* rve,
227 293
 					struct rval_expr** bad_rve, enum rval_type* bad_type,
228 294
 					enum rval_type* exp_type);
... ...
@@ -233,10 +299,27 @@ char* rval_type_name(enum rval_type type);
233 299
   */
234 300
 struct rval_expr* mk_rval_expr_v(enum rval_type rv_type, void* val,
235 301
 									struct cfg_pos* pos);
236
-/** create a unary op. rval_expr.. */
302
+
303
+/**
304
+ * @brief Create a unary op. rval_expr
305
+ * ret= op rve1
306
+ * @param op   - rval expr. unary operator
307
+ * @param rve1 - rval expr. on which the operator will act.
308
+ * @param pos configuration position
309
+ * @return new pkg_malloc'ed rval_expr or 0 on error.
310
+ */
237 311
 struct rval_expr* mk_rval_expr1(enum rval_expr_op op, struct rval_expr* rve1,
238 312
 									struct cfg_pos* pos);
239
-/** create a rval_expr. from 2 other rval exprs, using op. */
313
+
314
+/**
315
+ * @brief Create a rval_expr. from 2 other rval exprs, using op
316
+ * ret = rve1 op rve2
317
+ * @param op   - rval expr. operator
318
+ * @param rve1 - rval expr. on which the operator will act.
319
+ * @param rve2 - rval expr. on which the operator will act.
320
+ * @param pos configuration position
321
+ * @return new pkg_malloc'ed rval_expr or 0 on error.
322
+ */
240 323
 struct rval_expr* mk_rval_expr2(enum rval_expr_op op, struct rval_expr* rve1,
241 324
 													  struct rval_expr* rve2,
242 325
 													  struct cfg_pos* pos);