E SVN: gastal trunk/ecore/src/lib/ecore

[Enlightenment S. <no-...@en...>]

Log:
Ecore event functions docs improvements.
  
  Moved docs to header file.
  Fixed some typos.
  Added @brief.
  Add failure information to @return.
  Other random improvements.

Author:       gastal
Date:         2012-03-14 06:22:20 -0700 (Wed, 14 Mar 2012)
New Revision: 69337
Trac:         http://trac.enlightenment.org/e/changeset/69337

Modified:
  trunk/ecore/src/lib/ecore/Ecore.h trunk/ecore/src/lib/ecore/ecore_events.c 

Modified: trunk/ecore/src/lib/ecore/Ecore.h
===================================================================
--- trunk/ecore/src/lib/ecore/Ecore.h	2012-03-14 13:03:38 UTC (rev 69336)
+++ trunk/ecore/src/lib/ecore/Ecore.h	2012-03-14 13:22:20 UTC (rev 69337)
@@ -664,16 +664,156 @@
 #endif
 };
 
+/**
+ * @brief Add an event handler.
+ * @param type The type of the event this handler will get called for
+ * @param func The function to call when the event is found in the queue
+ * @param data A data pointer to pass to the called function @p func
+ * @return A new Event handler, or NULL on failure
+ *
+ * Add an event handler to the list of handlers. This will, on success, return
+ * a handle to the event handler object that was created, that can be used
+ * later to remove the handler using ecore_event_handler_del(). The @p type
+ * parameter is the integer of the event type that will trigger this callback
+ * to be called. The callback @p func is called when this event is processed
+ * and will be passed the event type, a pointer to the private event
+ * structure that is specific to that event type, and a data pointer that is
+ * provided in this call as the @p data parameter.
+ *
+ * When the callback @p func is called, it must return 1 or 0. If it returns
+ * 1 (or ECORE_CALLBACK_PASS_ON), It will keep being called as per normal, for
+ * each handler set up for that event type. If it returns 0 (or
+ * ECORE_CALLBACK_DONE), it will cease processing handlers for that particular
+ * event, so all handler set to handle that event type that have not already
+ * been called, will not be.
+ */
 EAPI Ecore_Event_Handler *ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data);
+/**
+ * @brief Delete an event handler.
+ * @param event_handler Event handler handle to delete
+ * @return Data passed to handler
+ *
+ * Delete a specified event handler from the handler list. On success this will
+ * delete the event handler and return the pointer passed as @p data when the
+ * handler was added by ecore_event_handler_add(). On failure NULL will be
+ * returned. Once a handler is deleted it will no longer be called.
+ */
 EAPI void *ecore_event_handler_del(Ecore_Event_Handler *event_handler);
+/**
+ * @brief Add an event to the event queue.
+ * @param type The event type to add to the end of the event queue
+ * @param ev The data structure passed as @c event to event handlers
+ * @param func_free The function to be called to free @a ev
+ * @param data The data pointer to be passed to the free function
+ * @return A Handle for that event on success, otherwise NULL
+ *
+ * If it succeeds, an event of type @a type will be added to the queue for
+ * processing by event handlers added by ecore_event_handler_add(). The @a ev
+ * parameter will be passed as the @c event parameter of the handler. When the
+ * event is no longer needed, @a func_free will be called and passed @a ev for
+ * cleaning up. If @p func_free is NULL, free() will be called with the private
+ * structure pointer.
+ */
 EAPI Ecore_Event *ecore_event_add(int type, void *ev, Ecore_End_Cb func_free, void *data);
+/**
+ * @brief Delete an event from the queue.
+ * @param event The event handle to delete
+ * @return The data pointer originally set for the event free function
+ *
+ * This deletes the event @p event from the event queue, and returns the
+ * @p data parameter originally set when adding it with ecore_event_add(). This
+ * does not immediately call the free function, and it may be called later on
+ * cleanup, and so if the free function depends on the data pointer to work,
+ * you should defer cleaning of this till the free function is called later.
+ */
 EAPI void *ecore_event_del(Ecore_Event *event);
+/**
+ * @brief Get the data associated with an #Ecore_Event_Handler
+ * @param eh The event handler
+ * @return The data
+ *
+ * This function returns the data previously associated with @p eh by
+ * ecore_event_handler_add().
+ */
 EAPI void *ecore_event_handler_data_get(Ecore_Event_Handler *eh);
+/**
+ * @brief Set the data associated with an #Ecore_Event_Handler
+ * @param eh The event handler
+ * @param data The data to associate
+ * @return The previous data
+ *
+ * This function sets @p data to @p eh and returns the old data pointer
+ * which was previously associated with @p eh by ecore_event_handler_add().
+ */
 EAPI void *ecore_event_handler_data_set(Ecore_Event_Handler *eh, const void *data);
+/**
+ * @brief Allocate a new event type id sensibly and return the new id.
+ * @return A new event type id.
+ *
+ * This function allocates a new event type id and returns it. Once an event
+ * type has been allocated it can never be de-allocated during the life of
+ * the program. There is no guarantee of the contents of this event ID, or how
+ * it is calculated, except that the ID will be unique to the current instance
+ * of the process.
+ */
 EAPI int ecore_event_type_new(void);
+/**
+ * @brief Add a filter the current event queue.
+ *
+ * @param func_start Function to call just before filtering and return data
+ * @param func_filter Function to call on each event
+ * @param func_end Function to call after the queue has been filtered
+ * @param data Data to pass to the filter functions
+ * @return A filter handle on success, NULL otherwise
+ *
+ * Adds a callback to filter events from the event queue. Filters are called on
+ * the queue just before Event handler processing to try and remove redundant
+ * events. Just as processing is about to start @a func_start is called and
+ * passed the @a data pointer, the return value of this functions is passed to
+ * @a func_filter as loop_data. @a func_filter is also passed @a data and the
+ * event type and event structure. If this @a func_filter returns #EINA_FALSE,
+ * the event is removed from the queue, if it returns #EINA_TRUE, the event is
+ * kept. When processing is finished @p func_end is called and is passed the
+ * loop_data(returned by @c func_start) and @p data pointer to clean up.
+ */
 EAPI Ecore_Event_Filter *ecore_event_filter_add(Ecore_Data_Cb func_start, Ecore_Filter_Cb func_filter, Ecore_End_Cb func_end, const void *data);
+/**
+ * @brief Delete an event filter.
+ * @param ef The event filter handle
+ * @return The data set for the filter on success, NULL otherwise
+ *
+ * Delete a filter that has been added by its @p ef handle.
+ */
 EAPI void *ecore_event_filter_del(Ecore_Event_Filter *ef);
+/**
+ * @brief Return the current event type being handled.
+ * @return The current event type being handled if inside a handler callback,
+ * ECORE_EVENT_NONE otherwise
+ *
+ * If the program is currently inside an Ecore event handler callback this
+ * will return the type of the current event being processed.
+ *
+ * This is useful when certain Ecore modules such as Ecore_Evas "swallow"
+ * events and not all the original information is passed on. In special cases
+ * this extra information may be useful or needed and using this call can let
+ * the program know if the event type being handled is one it wants to get more
+ * information about.
+ */
 EAPI int ecore_event_current_type_get(void);
+/**
+ * @brief Return the current event type pointer handled.
+ * @return The current event pointer being handled if inside a handler callback,
+ * NULL otherwise
+ *
+ * If the program is currently inside an Ecore event handler callback this
+ * will return the pointer of the current event being processed.
+ *
+ * This is useful when certain Ecore modules such as Ecore_Evas "swallow"
+ * events and not all the original information is passed on. In special cases
+ * this extra information may be useful or needed and using this call can let
+ * the program access the event data if the type of the event is handled by
+ * the program.
+ */
 EAPI void *ecore_event_current_event_get(void);
 
 /**

Modified: trunk/ecore/src/lib/ecore/ecore_events.c
===================================================================
--- trunk/ecore/src/lib/ecore/ecore_events.c	2012-03-14 13:03:38 UTC (rev 69336)
+++ trunk/ecore/src/lib/ecore/ecore_events.c	2012-03-14 13:22:20 UTC (rev 69337)
@@ -72,35 +72,6 @@
 static void  _ecore_event_purge_deleted(void);
 static void *_ecore_event_del(Ecore_Event *event);
 
-/**
- * @addtogroup Ecore_Event_Group
- *
- * @{
- */
-
-/**
- * Add an event handler.
- * @param type The type of the event this handler will get called for
- * @param func The function to call when the event is found in the queue
- * @param data A data pointer to pass to the called function @p func
- * @return A new Event handler, or NULL on failure
- *
- * Add an event handler to the list of handlers. This will, on success, return
- * a handle to the event handler object that was created, that can be used
- * later to remove the handler using ecore_event_handler_del(). The @p type
- * parameter is the integer of the event type that will trigger this callback
- * to be called. The callback @p func is called when this event is processed
- * and will be passed the event type, a pointer to the private event
- * structure that is specific to that event type, and a data pointer that is
- * provided in this call as the @p data parameter.
- *
- * When the callback @p func is called, it must return 1 or 0. If it returns
- * 1 (or ECORE_CALLBACK_PASS_ON), It will keep being called as per normal, for
- * each handler set up for that event type. If it returns 0 (or
- * ECORE_CALLBACK_DONE), it will cease processing handlers for that particular
- * event, so all handler set to handle that event type that have not already
- * been called, will not be.
- */
 EAPI Ecore_Event_Handler *
 ecore_event_handler_add(int                    type,
                         Ecore_Event_Handler_Cb func,
@@ -151,16 +122,6 @@
    return eh;
 }
 
-/**
- * Delete an event handler.
- * @param event_handler Event handler handle to delete
- * @return Data passed to handler
- *
- * Delete a specified event handler from the handler list. On success this will
- * delete the event handler and return the pointer passed as @p data when the
- * handler was added by ecore_event_handler_add(). On failure NULL will be
- * returned. Once a handler is deleted it will no longer be called.
- */
 EAPI void *
 ecore_event_handler_del(Ecore_Event_Handler *event_handler)
 {
@@ -180,14 +141,6 @@
    return data;
 }
 
-/**
- * @brief Get the data associated with an #Ecore_Event_Handler
- * @param eh The event handler
- * @return The data
- *
- * This function returns the data previously associated with @p eh by
- * ecore_event_handler_add().
- */
 EAPI void *
 ecore_event_handler_data_get(Ecore_Event_Handler *eh)
 {
@@ -205,15 +158,6 @@
    return data;
 }
 
-/**
- * @brief Set the data associated with an #Ecore_Event_Handler
- * @param eh The event handler
- * @param data The data to associate
- * @return The previous data
- *
- * This function sets @p data to @p eh and returns the old data pointer
- * which was previously associated with @p eh by ecore_event_handler_add().
- */
 EAPI void *
 ecore_event_handler_data_set(Ecore_Event_Handler *eh,
                              const void          *data)
@@ -241,21 +185,6 @@
    free(event);
 }
 
-/**
- * @brief Add an event to the event queue.
- * @param type The event type to add to the end of the event queue
- * @param ev The data structure passed as @c event to event handlers
- * @param func_free The function to be called to free @a ev
- * @param data The data pointer to be passed to the free function
- * @return A Handle for that event on success, otherwise NULL
- *
- * If it succeeds, an event of type @a type will be added to the queue for
- * processing by event handlers added by ecore_event_handler_add(). The @a ev
- * parameter will be passed as the @c event parameter of the handler. When the
- * event is no longer needed, @a func_free will be called and passed @a ev for
- * cleaning up. If @p func_free is NULL, free() will be called with the private
- * structure pointer.
- */
 EAPI Ecore_Event *
 ecore_event_add(int          type,
                 void        *ev,
@@ -276,17 +205,6 @@
    return event;
 }
 
-/**
- * Delete an event from the queue.
- * @param event The event handle to delete
- * @return The data pointer originally set for the event free function
- *
- * This deletes the event @p event from the event queue, and returns the
- * @p data parameer originally set when adding it with ecore_event_add(). This
- * does not immediately call the free function, and it may be called later on
- * cleanup, and so if the free function depends on the data pointer to work,
- * you should defer cleaning of this till the free function is called later.
- */
 EAPI void *
 ecore_event_del(Ecore_Event *event)
 {
@@ -306,16 +224,6 @@
    return data;
 }
 
-/**
- * Allocate a new event type id sensibly and return the new id.
- * @return A new event type id.
- *
- * This function allocates a new event type id and returns it. Once an event
- * type has been allocated it can never be de-allocated during the life of
- * the program. There is no guarantee of the contents of this event ID, or how
- * it is calculated, except that the ID will be unique to the current instance
- * of the process.
- */
 EAPI int
 ecore_event_type_new(void)
 {
@@ -328,26 +236,6 @@
    return id;
 }
 
-/**
- * Add a filter the current event queue.
- * @param func_start Function to call just before filtering and return data
- * @param func_filter Function to call on each event
- * @param func_end Function to call after the queu has been filtered
- * @param data Data to pass to the filter functions
- * @return A filter handle
- *
- * This adds a filter to call callbacks to loop through the event queue and
- * filter events out of the queue. On failure NULL is returned. On success a
- * Filter handle is returned. Filters are called on the queue just before
- * Event handler processing to try and remove redundant events. Just as
- * processing starts @p func_start is called and passed the @p data pointer.
- * This function returns a pointer that is used as loop_data that is now passed to
- * @p func_filter as loop_data. @p func_filter is also passed @p data and the
- * event type and private event structure. If this callback returns 0, the
- * event is removed from the queue. If it returns 1, the event is kept. When
- * processing is finished @p func_end is called and is passed the loop_data
- * and @p data pointer to clean up.
- */
 EAPI Ecore_Event_Filter *
 ecore_event_filter_add(Ecore_Data_Cb   func_start,
                        Ecore_Filter_Cb func_filter,
@@ -371,15 +259,6 @@
    return ef;
 }
 
-/**
- * Delete an event filter.
- * @param ef The event filter handle
- * @return The data set for the filter
- *
- * Delete a filter that has been added by its @p ef handle. On success this
- * will return the data pointer set when this filter was added. On failure
- * NULL is returned.
- */
 EAPI void *
 ecore_event_filter_del(Ecore_Event_Filter *ef)
 {
@@ -401,50 +280,18 @@
    return data;
 }
 
-/**
- * Return the current event type being handled.
- * @return The current event type being handled if inside a handler callback
- *
- * If the program is currently inside an Ecore event handler callback this
- * will return the type of the current event being processed. If Ecore is
- * not inside an event handler, ECORE_EVENT_NONE is returned.
- *
- * This is useful when certain Ecore modules such as Ecore_Evas "swallow"
- * events and not all the original information is passed on. In special cases
- * this extra information may be useful or needed and using this call can let
- * the program know if the event type being handled is one it wants to get more
- * information about.
- */
 EAPI int
 ecore_event_current_type_get(void)
 {
    return ecore_raw_event_type;
 }
 
-/**
- * Return the current event type pointer handled.
- * @return The current event pointer being handled if inside a handler callback
- *
- * If the program is currently inside an Ecore event handler callback this
- * will return the pointer of the current event being processed. If Ecore is
- * not inside an event handler, NULL will be returned.
- *
- * This is useful when certain Ecore modules such as Ecore_Evas "swallow"
- * events and not all the original information is passed on. In special cases
- * this extra information may be useful or needed and using this call can let
- * the program access the event data if the type of the event is handled by
- * the program.
- */
 EAPI void *
 ecore_event_current_event_get(void)
 {
    return ecore_raw_event_event;
 }
 
-/**
- * @}
- */
-
 EAPI void *
 _ecore_event_handler_del(Ecore_Event_Handler *event_handler)
 {