Doxygen changes.

svn path=/trunk/; revision=33981

1 files changed, 56 insertions, 5 deletions

diff --git a/epan/range.h b/epan/range.h
index 1d10801bd8..1022e7b321 100644
--- a/epan/range.h
+++ b/epan/range.h
@@ -30,7 +30,11 @@
 
 #include <glib.h>
 
-/* XXX where's the best place for these? */
+/** @file
+ * Range strings a variant of value_strings
+ */
+
+/**@todo where's the best place for these? */
 #define MAX_SCTP_PORT 65535
 #define MAX_TCP_PORT 65535
 #define MAX_UDP_PORT 65535
@@ -41,13 +45,13 @@ typedef struct range_admin_tag {
     guint32 high;
 } range_admin_t;
 
+/** user specified range(s) */
 typedef struct range {
-    /* user specified range(s) */
-    guint           nranges;   /* number of entries in ranges */
-    range_admin_t   ranges[1]; /* variable-length array */
+    guint           nranges;   /**< number of entries in ranges */
+    range_admin_t   ranges[1]; /**< variable-length array */
 } range_t;
 
-/*
+/**
  * Return value from range_convert_str().
  */
 typedef enum {
@@ -58,17 +62,64 @@ typedef enum {
 
 extern range_t *range_empty(void);
 
+
+/*** Converts a range string to a fast comparable array of ranges.
+ * This function allocates a range_t large enough to hold the number
+ * of ranges specified, and fills the array range->ranges containing
+ * low and high values with the number of ranges being range->nranges.
+ * After having called this function, the function value_is_in_range()
+ * determines whether a given number is within the range or not.<BR>
+ * In case of a single number, we make a range where low is equal to high. 
+ * We take care on wrongly entered ranges; opposite order will be taken
+ * care of.
+ * 
+ * The following syntax is accepted :
+ *
+ *   1-20,30-40     Range from 1 to 20, and packets 30 to 40
+ *   -20,30         Range from 1 to 20, and packet 30
+ *   20,30,40-      20, 30, and the range from 40 to the end
+ *   20-10,30-25    Range from 10 to 20, and from 25 to 30
+ *   -              All values
+ * @param range the range
+ * @param es points to the string to be converted.
+ * @param max_value' specifies the maximum value in a range.
+ * @return 
+ */
 extern convert_ret_t range_convert_str(range_t **range, const gchar *es,
     guint32 max_value);
 
+/** This function returns TRUE if a given value is within one of the ranges
+ * stored in the ranges array.
+ * @param range the range
+ * @param val the value to check
+ * @return TRUE if the value is in range
+ */
 extern gboolean value_is_in_range(range_t *range, guint32 val);
 
+/** This function returns TRUE if the two given range_t's are equal.
+ * @param a first range
+ * @param b second range
+ * @return TRUE if the value is in range
+ */
 extern gboolean ranges_are_equal(range_t *a, range_t *b);
 
+/** This function calls the provided callback function for each value in
+ * in the range.
+ * @param range the range
+ * @param val value
+ */
 extern void range_foreach(range_t *range, void (*callback)(guint32 val));
 
+/** 
+ * This function converts a range_t to a (ep_alloc()-allocated) string. 
+ */
 extern char *range_convert_range(range_t *range);
 
+/**
+ * Create a copy of a range.
+ * @param src the range to copy
+ * @return ep allocated copy of the range
+ */
 extern range_t *range_copy(range_t *src);
 
 #endif /* __RANGE_H__ */