Some restructuring, clean up, grouping, explaining, etc. Getting there...

SVN revision: 11696

legacy/ecore/ecore.c.in

@@ -25,10 +25,16 @@ These routines are used for Ecore Library interaction
 
 Ecore is a library of convenience functions.
 
-Currently, Ecore provides the following modules:
-@li @ref Ecore_Main_Loop_Page
-@li @ref Ecore_Config_Page
-@li @ref X_Window_System_Page
+The Ecore library provides the following modules:
+@li @link Ecore.h        Ecore - Main Loop Functions. @endlink
+@li @link Ecore_Con.h    Ecore_Con - Connection functions. @endlink
+@li @link Ecore_Config.h Ecore_Config - Configuration functions. @endlink
+@li @link Ecore_Evas.h   Ecore_Evas - Evas convenience functions. @endlink
+@li @link Ecore_Fb.h     Ecore_FB - Frame buffer convenience functions. @endlink
+@li @link Ecore_Ipc.h    Ecore_IPC - Inter Process Communication functions. @endlink
+@li @link Ecore_Job.h    Ecore_Job - Job functions, to be used in the Ecore main loop. @endlink
+@li @link Ecore_Txt.h    Ecore_Txt - Text encoding conversion. @endlink
+@li @link Ecore_X.h      Ecore_X - X Windows System wrapper. @endlink
 
 @section compiling How to compile using Ecore?
 
@@ -64,7 +70,7 @@ make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro"
 
 */
 
-/**
+/*
 @page Ecore_Main_Loop_Page The Ecore Main Loop
 
 @section intro What is Ecore?
@@ -188,33 +194,6 @@ follows the same principles as shown in this example.
 
 */
 
-/**
-@page Ecore_Con_Page The Ecore Connection Library
-
-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.
-
- */
-
 /**
 @page Ecore_Config_Page The Enlightened Property Library
 
@@ -290,12 +269,6 @@ that are used.
 
 // GROUP DEFINITIONS
 
-/**
-@defgroup Ecore_Main_Loop_Group Main Loop Functions
-
-Functions used to control the main loop.
-*/
-
 /**
 @defgroup Ecore_Timer_Group Ecore Timer
 

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

@@ -6,9 +6,18 @@
  * @brief The file that provides the program utility, main loop and timer
  *        functions.
  *
- * The following groups of functions are included with this file:
- * @li @ref Ecore_Exe_Basic_Group
- * @li @ref Ecore_Exe_Signal_Group
+ * This header provides the Ecore event handling loop.  For more
+ * details, see @ref Ecore_Main_Loop_Group.
+ *
+ * For the main loop to be of any use, you need to be able to add events
+ * and event handlers.
+ *
+ * There is also provision for callbacks for when the loop enters or
+ * exits an idle state. See @ref Idle_Group for more information.
+ *
+ * Functions are also provided for spawning child processes using fork.
+ * See @ref Ecore_Exe_Basic_Group and @ref Ecore_Exe_Signal_Group for
+ * more details.
  */
 
 #include <sys/types.h>

legacy/ecore/src/lib/ecore/ecore_main.c

@@ -31,11 +31,29 @@ static double            t1 = 0.0;
 static double            t2 = 0.0;
 
 /**
- * Run 1 iteration of the main loop and process everything on the queue.
- * @ingroup Ecore_Main_Loop_Group
+ * @defgroup Ecore_Main_Loop_Group Main Loop Functions
+ *
+ * These functions control the Ecore event handling loop.  This loop is
+ * designed to work on embedded systems all the way to large and
+ * powerful mutli-cpu workstations.
+ *
+ * It serialises all system signals and events into a single event
+ * queue, that can be easily processed without needing to worry about
+ * concurrency.  A properly written, event-driven program using this
+ * kind of programming does not need threads.  It makes the program very
+ * robust and easy to follow.
  * 
- * This function Processes 1 iteration of the main loop, handling anything on
- * the queue. See ecore_main_loop_begin() for more information.
+ * Here is an example of simple program and its basic event loop flow:
+ * @image html prog_flow.png
+ *
+ * For examples of setting up and using a main loop, see
+ * @ref event_handler_example.c and @ref timer_example.c.
+ */
+
+/**
+ * Runs a single iteration of the main loop to process everything on the
+ * queue.
+ * @ingroup Ecore_Main_Loop_Group
  */
 void
 ecore_main_loop_iterate(void)
@@ -44,13 +62,11 @@ ecore_main_loop_iterate(void)
 }
 
 /**
- * Run the application main loop.
+ * Runs the application main loop.
+ *
+ * This function will not return until @ref ecore_main_loop_quit is called.
+ *
  * @ingroup Ecore_Main_Loop_Group
- * 
- * This function does not return until ecore_main_loop_quit() is called. It
- * will keep looping internally and call all callbacks set up to handle timers,
- * idle state and events Ecore recieves from X, fd's, IPC, signals etc. and
- * anything else that has registered a handler with ecore itself.
  */
 void
 ecore_main_loop_begin(void)
@@ -62,12 +78,9 @@ ecore_main_loop_begin(void)
 }
 
 /**
- * Quit the main loop after it is done processing.
+ * Quits the main loop once all the events currently on the queue have
+ * been processed.
  * @ingroup Ecore_Main_Loop_Group
- * 
- * This function will flag a quit of the main loop once the current loop has
- * finished processing all events. It will not quit instantly, so expect more
- * callbacks to be called after this command has been issued.
  */
 void
 ecore_main_loop_quit(void)
@@ -75,6 +88,12 @@ ecore_main_loop_quit(void)
    do_quit = 1;
 }
 
+/**
+ * @defgroup Ecore_FD_Handler_Group File Event Handling Functions
+ *
+ * To be written.
+ */
+
 /**
  * Add a handler for read/write notification of a file descriptor.
  * @param fd The file descriptor to watch
@@ -155,11 +174,10 @@ ecore_main_fd_handler_del(Ecore_Fd_Handler *fd_handler)
 }
 
 /**
- * Return the file descriptor that the handler is handling
- * @param fd_handler The fd handler to query
- * @return The fd the handler is watching
- * 
- * This returns the fd the @p fd_handler is monitoring.
+ * Returns the file descriptor that the given handler is handling.
+ * @param   fd_handler The given FD handler.
+ * @return  The file descriptor the handler is watching
+ * @ingroup Ecore_FD_Handler_Group
  */
 int
 ecore_main_fd_handler_fd_get(Ecore_Fd_Handler *fd_handler)

legacy/ecore/src/lib/ecore_con/ecore_con.c

@@ -46,10 +46,18 @@ static int init_count = 0;
 
 #define LENGTH_OF_SOCKADDR_UN(s) (strlen((s)->sun_path) + (size_t)(((struct sockaddr_un *)NULL)->sun_path))
 
+/**
+ * @defgroup Ecore_Con_Lib_Group Ecore Connection Library Functions
+ *
+ * Utility functions that set up and shut down the Ecore Connection
+ * library.
+ */
+
 /**
  * Initialises the Ecore_Con library.
- * @return Number of times the library has been initialised without being
- *         shut down.
+ * @return  Number of times the library has been initialised without being
+ *          shut down.
+ * @ingroup Ecore_Con_Lib_Group
  */
 int
 ecore_con_init(void)
@@ -74,8 +82,9 @@ ecore_con_init(void)
 
 /**
  * Shuts down the Ecore_Con library.
- * @return Number of times the library has been initialised without being
- *         shut down.
+ * @return  Number of times the library has been initialised without being
+ *          shut down.
+ * @ingroup Ecore_Con_Lib_Group
  */
 int
 ecore_con_shutdown(void)
@@ -89,6 +98,12 @@ ecore_con_shutdown(void)
    return 0;
 }
 
+/**
+ * @defgroup Ecore_Con_Server_Group Ecore Connection Server Functions
+ *
+ * Functions that operate on Ecore server objects.
+ */
+
 /**
  * Creates a server to listen for connections.
  *
@@ -113,6 +128,7 @@ ecore_con_shutdown(void)
  * @param  data       Data to associate with the created Ecore_Con_Server
  *                    object.
  * @return A new Ecore_Con_Server.
+ * @ingroup Ecore_Con_Server_Group
  */
 Ecore_Con_Server *
 ecore_con_server_add(Ecore_Con_Type compl_type,
@@ -331,6 +347,7 @@ ecore_con_server_add(Ecore_Con_Type compl_type,
  * @param  data       Data to associate with the created Ecore_Con_Server
  *                    object.
  * @return A new Ecore_Con_Server.
+ * @ingroup Ecore_Con_Server_Group
  */
 Ecore_Con_Server *
 ecore_con_server_connect(Ecore_Con_Type compl_type,
@@ -478,8 +495,9 @@ ecore_con_server_connect(Ecore_Con_Type compl_type,
 
 /**
  * Closes the connection and frees the given server.
- * @param  svr The given server.
- * @return Data associated with the server when it was created.
+ * @param   svr The given server.
+ * @return  Data associated with the server when it was created.
+ * @ingroup Ecore_Con_Server_Group
  */
 void *
 ecore_con_server_del(Ecore_Con_Server *svr)
@@ -499,8 +517,9 @@ ecore_con_server_del(Ecore_Con_Server *svr)
 
 /**
  * Retrieves the data associated with the given server.
- * @param  svr The given server.
- * @return The associated data.
+ * @param   svr The given server.
+ * @return  The associated data.
+ * @ingroup Ecore_Con_Server_Group
  */
 void *
 ecore_con_server_data_get(Ecore_Con_Server *svr)
@@ -517,8 +536,9 @@ ecore_con_server_data_get(Ecore_Con_Server *svr)
 /**
  * Retrieves whether the given server is currently connected.
  * @todo Check that this function does what the documenter believes it does.
- * @param  svr The given server.
- * @return @c 1 if the server is connected.  @c 0 otherwise.
+ * @param   svr The given server.
+ * @return  @c 1 if the server is connected.  @c 0 otherwise.
+ * @ingroup Ecore_Con_Server_Group
  */
 int
 ecore_con_server_connected_get(Ecore_Con_Server *svr)
@@ -535,11 +555,12 @@ ecore_con_server_connected_get(Ecore_Con_Server *svr)
 
 /**
  * Sends the given data to the given server.
- * @param  svr  The given server.
- * @param  data The given data.
- * @param  size Length of the data, in bytes, to send.
- * @return The number of bytes sent.  @c 0 will be returned if there is an
- *         error.
+ * @param   svr  The given server.
+ * @param   data The given data.
+ * @param   size Length of the data, in bytes, to send.
+ * @return  The number of bytes sent.  @c 0 will be returned if there is an
+ *          error.
+ * @ingroup Ecore_Con_Server_Group
  */
 int
 ecore_con_server_send(Ecore_Con_Server *svr, void *data, int size)
@@ -573,14 +594,21 @@ ecore_con_server_send(Ecore_Con_Server *svr, void *data, int size)
      }
    return size;
 }
-  
+
+/**
+ * @defgroup Ecore_Con_Client_Group Ecore Connection Client Functions
+ *
+ * Functions that operate on Ecore connection client objects.
+ */
+
 /**
  * Sends the given data to the given client.
- * @param  cl   The given client.
- * @param  data The given data.
- * @param  size Length of the data, in bytes, to send.
- * @return The number of bytes sent.  @c 0 will be returned if there is an
- *         error.
+ * @param   cl   The given client.
+ * @param   data The given data.
+ * @param   size Length of the data, in bytes, to send.
+ * @return  The number of bytes sent.  @c 0 will be returned if there is an
+ *          error.
+ * @ingroup Ecore_Con_Client_Group
  */
 int
 ecore_con_client_send(Ecore_Con_Client *cl, void *data, int size)
@@ -618,8 +646,9 @@ ecore_con_client_send(Ecore_Con_Client *cl, void *data, int size)
 /**
  * Retrieves the server representing the socket the client has
  * connected to.
- * @param  cl The given client.  
- * @return The server that the client connected to.
+ * @param   cl The given client.  
+ * @return  The server that the client connected to.
+ * @ingroup Ecore_Con_Client_Group
  */
 Ecore_Con_Server *
 ecore_con_client_server_get(Ecore_Con_Client *cl)
@@ -635,8 +664,9 @@ ecore_con_client_server_get(Ecore_Con_Client *cl)
 
 /**
  * Closes the connection and frees memory allocated to the given client.
- * @param  cl The given client.
- * @return Data associated with the client.
+ * @param   cl The given client.
+ * @return  Data associated with the client.
+ * @ingroup Ecore_Con_Client_Group
  */
 void *
 ecore_con_client_del(Ecore_Con_Client *cl)
@@ -656,8 +686,9 @@ ecore_con_client_del(Ecore_Con_Client *cl)
 
 /**
  * Sets the data associated with the given client to @p data.
- * @param cl   The given client.
- * @param data What to set the data to.
+ * @param   cl   The given client.
+ * @param   data What to set the data to.
+ * @ingroup Ecore_Con_Client_Group
  */
 void
 ecore_con_client_data_set(Ecore_Con_Client *cl, const void *data)
@@ -673,8 +704,9 @@ ecore_con_client_data_set(Ecore_Con_Client *cl, const void *data)
 
 /**
  * Retrieves the data associated with the given client.
- * @param  cl The given client.
- * @return The data associated with @p cl.
+ * @param   cl The given client.
+ * @return  The data associated with @p cl.
+ * @ingroup Ecore_Con_Client_Group
  */
 void *
 ecore_con_client_data_get(Ecore_Con_Client *cl)

legacy/ecore/src/lib/ecore_x/Ecore_X.h

@@ -7,7 +7,14 @@
 
 /**
  * @file
- * @brief Ecore functions for dealing with the X Windows system
+ * @brief Ecore functions for dealing with the X Windows System
+ *
+ * Ecore_X provides a wrapper and convenience functions for using the
+ * X Windows System.  Function groups for this part of the library 
+ * include the following:
+ * @li @ref Ecore_X_Init_Group
+ * @li @ref Ecore_X_Display_Attr_Group
+ * @li @ref Ecore_X_Flush_Group
  */
 
 typedef unsigned int Ecore_X_ID;

legacy/ecore/src/lib/ecore_x/ecore_x.c

@@ -211,7 +211,7 @@ int ECORE_X_LOCK_NUM = 0;
 int ECORE_X_LOCK_CAPS = 0;
 
 /**
- * @defgroup Ecore_X_Init_Group Ecore X Library Init and Shutdown Functions
+ * @defgroup Ecore_X_Init_Group X Library Init and Shutdown Functions
  *
  * Functions that start and shut down the Ecore X Library.
  */
@@ -537,7 +537,7 @@ ecore_x_disconnect(void)
 }
 
 /**
- * @defgroup Ecore_X_Display_Attr_Group Ecore X Display Attributes
+ * @defgroup Ecore_X_Display_Attr_Group X Display Attributes
  *
  * Functions that set and retrieve X display attributes.
  */
@@ -596,7 +596,7 @@ ecore_x_double_click_time_get(void)
 }
 
 /**
- * @defgroup Ecore_X_Flush_Group Ecore X Synchronization Functions
+ * @defgroup Ecore_X_Flush_Group X Synchronization Functions
  *
  * Functions that ensure that all commands that have been issued by the
  * Ecore X library have been sent to the server.