[svn-commits] russell: branch russell/event_performance r184034 - /team/russell/event_perfo...

[SVN commits to the Digium repositories]

Author: russell
Date: Tue Mar 24 16:07:17 2009
New Revision: 184034

URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=184034
Log:
add doxygen comments

Modified:
    team/russell/event_performance/main/event.c

Modified: team/russell/event_performance/main/event.c
URL: http://svn.digium.com/svn-view/asterisk/team/russell/event_performance/main/event.c?view=diff&rev=184034&r1=184033&r2=184034
==============================================================================
--- team/russell/event_performance/main/event.c (original)
+++ team/russell/event_performance/main/event.c Tue Mar 24 16:07:17 2009
@@ -56,8 +56,13 @@
 	unsigned char ie_payload[0];
 } __attribute__((packed));
 
+/*!
+ * \brief The payload for a string information element
+ */
 struct ast_event_ie_str_payload {
+	/*! \brief A hash calculated with ast_str_hash(), to speed up comparisons */
 	uint32_t hash;
+	/*! \brief The actual string, null terminated */
 	char str[1];
 } __attribute__((packed));
 
@@ -117,25 +122,69 @@
  * The event subscribers are indexed by which event they are subscribed to */
 static AST_RWDLLIST_HEAD(ast_event_sub_list, ast_event_sub) ast_event_subs[AST_EVENT_TOTAL];
 
+/*!
+ * \brief Compare two events
+ *
+ * \param[in] obj the first event, as an ast_event_ref
+ * \param[in] arg the second event, as an ast_event_ref
+ * \param[in] flags unused
+ *
+ * \pre Both events must be the same type.
+ * \pre The event type must be declared as a cached event type in ast_event_cache
+ *
+ * \details This function takes two events, and determines if they are considered
+ * equivalent.  The values of information elements specified in the cache arguments
+ * for the event type are used to determine if the events are equivalent.
+ *
+ * \retval 0 No match
+ * \retval CMP_MATCH The events are considered equivalent based on the cache arguments
+ */
+static int ast_event_cmp(void *obj, void *arg, int flags);
+
+/*!
+ * \brief Hash function for AST_EVENT_MWI
+ */
+static int ast_event_hash_mwi(const void *obj, const int flags);
+
+/*!
+ * \brief Hash function for AST_EVENT_DEVICE_STATE
+ */
+static int ast_event_hash_devstate(const void *obj, const int flags);
+
+/*!
+ * \brief Hash function for AST_EVENT_DEVICE_STATE_CHANGE
+ */
+static int ast_event_hash_devstate_change(const void *obj, const int flags);
+
 #ifdef LOW_MEMORY
 #define NUM_CACHE_BUCKETS 17
 #else
 #define NUM_CACHE_BUCKETS 563
 #endif
 
-static int ast_event_cmp(void *obj, void *arg, int flags);
-static int ast_event_hash_mwi(const void *obj, const int flags);
-static int ast_event_hash_devstate(const void *obj, const int flags);
-static int ast_event_hash_devstate_change(const void *obj, const int flags);
-
 #define MAX_CACHE_ARGS 8
 
 /*!
  * \brief Event types that are kept in the cache.
  */
 static struct {
+	/*! 
+	 * \brief Container of cached events
+	 *
+	 * \details This gets allocated in ast_event_init() when Asterisk starts
+	 * for the event types declared as using the cache.
+	 */
 	struct ao2_container *container;
+	/*! \brief Event type specific hash function */
 	ao2_hash_fn *hash_fn;
+	/*!
+	 * \brief Information Elements used for caching
+	 *
+	 * \details This array is the set of information elements that will be unique
+	 * among all events in the cache for this event type.  When a new event gets
+	 * cached, a previous event with the same values for these information elements
+	 * will be replaced.
+	 */
 	enum ast_event_ie_type cache_args[MAX_CACHE_ARGS];
 } ast_event_cache[AST_EVENT_TOTAL] = {
 	[AST_EVENT_MWI] = {