Ecore_Con module documentation, timer functions cleaned up, Time functions linked into Ecore.h docs.

SVN revision: 11704

legacy/ecore/src/lib/ecore/Ecore.h

@@ -13,6 +13,8 @@
  * and event handlers.  Events for file descriptor events are covered in
  * @ref Ecore_FD_Handler_Group.
  *
+ * Time functions are covered in @ref Ecore_Time_Group.
+ *
  * There is also provision for callbacks for when the loop enters or
  * exits an idle state. See @ref Idle_Group for more information.
  *

legacy/ecore/src/lib/ecore/ecore_time.c

@@ -4,12 +4,9 @@
 #include <sys/time.h>
 
 /**
- * Get the current system time as a floating point value in seconds.
- * @return The current time (since the epoch start) in seconds
- * 
- * This function returns the current system time in seconds from 12:00am 
- * 1st Janruary 1970. The time is returned as a double precision floating point
- * value to allow for fractions of a second to be determined.
+ * Retrieves the current system time as a floating point value in seconds.
+ * @return  The number of seconds since 12.00AM 1st January 1970.
+ * @ingroup Ecore_Time_Group
  */
 double
 ecore_time_get(void)

legacy/ecore/src/lib/ecore/ecore_timer.c

@@ -8,26 +8,20 @@ static int          timers_delete_me = 0;
 static Ecore_Timer *timers = NULL;
 
 /**
- * Add a timer to tick off in a specified time during main loop execution.
- * @param in The number of seconds in which to expire the timer
- * @param func The function to call when it expires
- * @param data The data to pass to the function
- * @return A handle to the new timer
- * @ingroup Ecore_Timer_Group
- * 
- * This function adds a timer and returns its handle on success and NULL on
- * failure. The function @p func will be called in @p in seconds from the
- * time this function call was made. The function @p func is passed the
- * @p data pointer as its parameter.
- * 
- * When the timer @p func is called, it must return a value of either 1 or 0. 
- * If it returns 1, it will be re-scheduled to repeat in the same interval
- * after this timer was triggered (ie if this timer was triggered with an
- * @p in value of 1.0 then the next timer will be triggered at the time this
- * timer was called plus 1.0).
- * 
- * For more information, see the @link timer_example.c ecore_timer @endlink
- * example.
+ * @defgroup Ecore_Time_Group Ecore Time Functions
+ *
+ * Functions that deal with time.  These functions include those that simply
+ * retrieve it in a given format, and those that create events based on it.
+ */
+
+/**
+ * Creates a timer to call the given function in the given period of time.
+ * @param   in   The interval in seconds.
+ * @param   func The given function.  If @p func returns 1, the timer is
+ *               rescheduled for the next interval @p in.
+ * @param   data Data to pass to @p func when it is called.
+ * @return  A timer object on success.  @c NULL on failure.
+ * @ingroup Ecore_Time_Group
  */
 Ecore_Timer *
 ecore_timer_add(double in, int (*func) (void *data), const void *data)
@@ -47,15 +41,10 @@ ecore_timer_add(double in, int (*func) (void *data), const void *data)
 
 /**
  * Delete the specified timer from the timer list.
- * @param timer The timer to delete
- * @return The data pointer set for the timer
- * @ingroup Ecore_Timer_Group
- * 
- * Delete the specified @p timer from the set of timers that are executed
- * during main loop execution. This function returns the data parameter that
- * was being passed to the callback on success, or NULL on failure. After this
- * call returns the specified timer object @p timer is invalid and should not
- * be used again. It will not get called again after deletion.
+ * @param   timer The timer to delete.
+ * @return  The data pointer set for the timer when @ref ecore_timer_add was
+ *          called.  @c NULL is returned if the function is unsuccessful.
+ * @ingroup Ecore_Time_Group
  */
 void *
 ecore_timer_del(Ecore_Timer *timer)

legacy/ecore/src/lib/ecore_con/Ecore_Con.h.in

@@ -4,6 +4,33 @@
 /**
  * @file Ecore_Con.h
  * @brief Sockets functions.
+ *
+ * The Ecore Connection Library ( @c Ecore_Con ) provides simple mechanisms
+ * for communications between programs using reliable sockets.  It saves
+ * the programmer from having to worry about file descripters and waiting
+ * for incoming connections.
+ *
+ * There are two main objects in the @c Ecore_Con library: the @c
+ * Ecore_Con_Server and the @c Ecore_Con_Client.
+ *
+ * The @c Ecore_Con_Server represents a server to connect to.  It is
+ * represents a server that can be connected to.  It is used regardless
+ * of whether the program is acting as a server or client itself.
+ *
+ * To create a listening server, call @c ecore_con_server_add().
+ *
+ * To connect to a server, call @c ecore_Con_server_connect().  Data can
+ * then be sent to the server using the @c ecore_con_server_send().
+ * 
+ * Whenever a client connection is made to an @c Ecore_Con_Server, a
+ * @c ECORE_CON_CLIENT_ADD event is emitted.  Any event callbacks that are
+ * called receive a @c Ecore_Con_Client object, which represents a
+ * connection that that particular client.
+ *
+ * Functions are described in the following groupings:
+ * @li @ref Ecore_Con_Lib_Group
+ * @li @ref Ecore_Con_Server_Group
+ * @li @ref Ecore_Con_Client_Group
  */
 
 #define HAVE_ECORE_CON_OPENSSL @USE_OPENSSL@