[ecore] Put order in header file, splitting function groups in contiguous chunks.

Sorry for having to pratically rewrite the header, but the other way
    to get docs right would be to put lots of @addtogroup around several
    chunks of the file, which is ugly too and doesn't organize anything.

    I have tested ecore with that and it seems to be okay.



SVN revision: 62307

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

@@ -74,7 +74,7 @@ static Eina_Lock _thread_safety;
 #endif
 
 /**
- * @addtogroup Ecore_Init_Group Ecore initialisation and shutdown functions.
+ * @addtogroup Ecore_Init_Group
  *
  * @{
  */
@@ -221,6 +221,10 @@ ecore_shutdown(void)
    return _ecore_init_count;
 }
 
+/**
+ * @}
+ */
+
 EAPI void
 ecore_main_loop_thread_safe_call(Ecore_Cb callback, void *data)
 {
@@ -249,10 +253,6 @@ ecore_main_loop_thread_safe_call(Ecore_Cb callback, void *data)
    eina_lock_release(&_thread_safety);
 }
 
-/**
- * @}
- */
-
 EAPI void
 ecore_print_warning(const char *function, const char *sparam)
 {

legacy/ecore/src/lib/ecore/ecore_app.c

@@ -21,13 +21,7 @@ static int app_argc = 0;
 static char **app_argv = NULL;
 
 /**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
-/**
- * @addtogroup Ecore_Application_Group Ecore Application functions
+ * @addtogroup Ecore_Application_Group
  *
  * @{
  */
@@ -95,7 +89,3 @@ ecore_app_restart(void)
 /**
  * @}
  */
-
-/**
- * @}
- */

legacy/ecore/src/lib/ecore/ecore_events.c

@@ -73,43 +73,7 @@ static void *_ecore_event_del(Ecore_Event *event);
 
 
 /**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
-/**
- * @addtogroup Ecore_Event_Group Ecore Event functions
- *
- * Ecore events are used to wake up the Ecore main loop to warn about state
- * changes, tasks completed, data available for reading or writing, etc. They
- * are the base of the event oriented programming.
- *
- * The idea is to write many functions (callbacks) that will be registered to
- * specific events, and called when these events happen. This way, when the
- * system state changes (a mouse click is detected, a key is pressed, or the
- * content of a file changes, for example), the respective callbacks will be
- * called with some information about that event. Usually the function/callback
- * will have a data pointer to the event info (the position in the screen where
- * the mouse was clicked, the name of the key that was pressed, or the name of
- * the file that has changed).
- *
- * The basic usage, when one needs to watch for an existing event, is to
- * register a callback to it using ecore_event_add(). Of course it's necessary
- * to know beforehand what are the types of events that the system/library will
- * emmit.  This should be available with the documentation from that
- * system/library.
- *
- * When writing a library or group of functions that need to inform about
- * something, and you already are running on top of a main loop, it is usually a
- * good approach to use events. This way you allow others to register as many
- * callbacks as necessary to this event, and don't have to care about who is
- * registering to it. The functions ecore_event_type_new() and ecore_event_add()
- * are available for this purpose.
- *
- * Example that deals with events:
- *
- * @li @ref ecore_event_example_c
+ * @addtogroup Ecore_Event_Group
  *
  * @{
  */
@@ -473,10 +437,6 @@ ecore_event_current_event_get(void)
    return ecore_raw_event_event;
 }
 
-/**
- * @}
- */
-
 /**
  * @}
  */

legacy/ecore/src/lib/ecore/ecore_exe.c

@@ -299,17 +299,8 @@ _ecore_exe_check_errno(int result, const char *file, int line)
    return result;
 }
 
-
 /**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
-/**
- * @addtogroup Ecore_Exe_Group Process Spawning Functions
- *
- * Functions that deal with and send signals to spawned processes.
+ * @addtogroup Ecore_Exe_Group
  *
  * @{
  */
@@ -1314,10 +1305,6 @@ ecore_exe_hup(Ecore_Exe *exe)
    kill(exe->pid, SIGHUP);
 }
 
-/**
- * @}
- */
-
 /**
  * @}
  */

legacy/ecore/src/lib/ecore/ecore_glib.c

@@ -220,13 +220,7 @@ _ecore_glib_shutdown(void)
 }
 
 /**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
-/**
- * @addtogroup Ecore_Main_Loop_Group Ecore Main Loop functions
+ * @addtogroup Ecore_Main_Loop_Group
  *
  * @}
  */
@@ -321,7 +315,3 @@ ecore_main_loop_glib_always_integrate_disable(void)
 /**
  * @}
  */
-
-/**
- * @}
- */

legacy/ecore/src/lib/ecore/ecore_idle_enterer.c

@@ -27,13 +27,7 @@ static void *
 _ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer);
 
 /**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
-/**
- * @addtogroup Ecore_Idle_Group Ecore Idle functions
+ * @addtogroup Ecore_Idle_Group
  *
  * @{
  */
@@ -119,10 +113,6 @@ ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer)
    return data;
 }
 
-/**
- * @}
- */
-
 /**
  * @}
  */

legacy/ecore/src/lib/ecore/ecore_idle_exiter.c

@@ -27,13 +27,7 @@ static void *
 _ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter);
 
 /**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
-/**
- * @addtogroup Ecore_Idle_Group Ecore Idle functions
+ * @addtogroup Ecore_Idle_Group
  *
  * @{
  */
@@ -88,10 +82,6 @@ ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter)
    return data;
 }
 
-/**
- * @}
- */
-
 /**
  * @}
  */

legacy/ecore/src/lib/ecore/ecore_idler.c

@@ -26,66 +26,6 @@ static int          idlers_delete_me = 0;
 static void *
 _ecore_idler_del(Ecore_Idler *idler);
 
-/**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
-/**
- * @addtogroup Ecore_Idle_Group Ecore Idle functions
- *
-Callbacks that are called when the program enters or exits an idle state.
-
-The ecore main loop enters an idle state when it is waiting for timers
-to time out, data to come in on a file descriptor or any other event
-to occur.  You can set callbacks to be called when the main loop
-enters an idle state, during an idle state or just after the program
-wakes up.
-
-Enterer callbacks are good for updating your program's state, if it
-has a state engine.  Once all of the enterer handlers are called, the
-program will enter a "sleeping" state.
-
-Idler callbacks are called when the main loop has called all enterer
-handlers.  They are useful for interfaces that require polling and
-timers would be too slow to use.
-
-If no idler callbacks are specified, then the process literally goes
-to sleep.  Otherwise, the idler callbacks are called continuously
-while the loop is "idle", using as much CPU as is available to the
-process.
-
-Exiter callbacks are called when the main loop wakes up from an idle
-state.
-
-@note Idle state doesn't mean that the @b program is idle, but that the <b>main
-loop</b> is idle. It doesn't have any timers, events, fd handlers or anything
-else to process (which in most <em>event driven</em> programs also means that the @b
-program is idle too, but it's not a rule). The program itself may be doing a lot of
-processing in the idler, or in another thread, for example.
-
-Example with functions that deal with idle state:
-
-@li @ref ecore_idler_example_c
-
- * @{
- */
-
-/**
- * Add an idler handler.
- * @param  func The function to call when idling.
- * @param  data The data to be passed to this @p func call.
- * @return A idler handle if successfully added.  NULL otherwise.
- *
- * Add an idler handle to the event loop, returning a handle on success and
- * NULL otherwise.  The function @p func will be called repeatedly while
- * no other events are ready to be processed, as long as it returns 1
- * (or ECORE_CALLBACK_RENEW). A return of 0 (or ECORE_CALLBACK_CANCEL) deletes
- * the idler.
- *
- * Idlers are useful for progressively prossessing data without blocking.
- */
 EAPI Ecore_Idler *
 ecore_idler_add(Ecore_Task_Cb func, const void *data)
 {
@@ -104,12 +44,6 @@ unlock:
    return ie;
 }
 
-/**
- * Delete an idler callback from the list to be executed.
- * @param  idler The handle of the idler callback to delete
- * @return The data pointer passed to the idler callback on success.  NULL
- *         otherwise.
- */
 EAPI void *
 ecore_idler_del(Ecore_Idler *idler)
 {

legacy/ecore/src/lib/ecore/ecore_job.c

@@ -36,28 +36,7 @@ _ecore_job_shutdown(void)
 }
 
 /**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
-/**
- * @addtogroup Ecore_Job_Group Ecore Job functions
- *
- * You can queue jobs that are to be done by the main loop when the current
- * event is dealt with.
- *
- * Jobs are processed by the main loop similarly to events. They also will be
- * executed in the order which they were added.
- *
- * A good use for them is when you don't want to execute an action immeditately,
- * but want to give the control back to the main loop so that it will call your
- * job callback when jobs start being processed (and if there are other jobs
- * added before yours, they will be processed first). This also gives the chance
- * to other actions in your program to cancel the job before it is started.
- *
- * Examples of using @ref Ecore_Job:
- * @li @ref ecore_job_example_c
+ * @addtogroup Ecore_Job_Group
  *
  * @{
  */
@@ -114,10 +93,6 @@ ecore_job_del(Ecore_Job *job)
    return data;
 }
 
-/**
- * @}
- */
-
 /**
  * @}
  */

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

@@ -790,29 +790,7 @@ _ecore_main_loop_shutdown(void)
 }
 
 /**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
-/**
- * @addtogroup Ecore_Main_Loop_Group Ecore 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.
- *
- * 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
- * Ecore_Main_Loop_Page.
+ * @addtogroup Ecore_Main_Loop_Group
  *
  * @{
  */
@@ -917,29 +895,6 @@ ecore_main_loop_select_func_get(void)
    return main_loop_select;
 }
 
-/**
- * @defgroup Ecore_FD_Handler_Group File Event Handling Functions
- *
- * Functions that deal with file descriptor handlers.
- *
- * The @ref Ecore_Fd_Handler can be used to watch a file descriptor for data
- * available for reading, for the availability to write without blocking, and
- * for errors on the file descriptor.
- *
- * ecore_main_fd_handler_add() is used to setup a handler for a given file
- * descriptor. This file descriptor can be the standard input, a network socket,
- * a stream received through some driver of a hardware decoder, etc. Thus it can
- * contain errors, like a disconnection, a broken pipe, and so, and that's why
- * it's possible to check for these errors with the @ref ECORE_FD_ERROR flag.
- *
- * An @ref Ecore_Fd_Handler can be used to watch on a file descriptor without
- * blocking, still being able to receive events, expire timers, and other watch
- * for other things that happen in the Ecore main loop.
- *
- * Example of use of a file descriptor handler:
- * @li @ref ecore_fd_handler_example_c
- */
-
 /**
  * Adds a callback for activity on the given file descriptor.
  *
@@ -1232,10 +1187,6 @@ unlock:
    _ecore_unlock();
 }
 
-/**
- * @}
- */
-
 /**
  * @}
  */

legacy/ecore/src/lib/ecore/ecore_pipe.c

@@ -89,30 +89,13 @@ struct _Ecore_Pipe
 
 static Eina_Bool _ecore_pipe_read(void *data, Ecore_Fd_Handler *fd_handler);
 
+
 /**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
+ * @addtogroup Ecore_Pipe_Group
  *
  * @{
  */
 
-/**
- * @addtogroup Ecore_Pipe_Group Pipe wrapper
- *
- * These functions wrap the pipe / write / read functions to easily integrate
- * its use into ecore's main loop.
- *
- * The ecore_pipe_add() function creates file descriptors (sockets on
- * Windows) and attach an handle to the ecore main loop. That handle is
- * called when data is read in the pipe. To write data in the pipe,
- * just call ecore_pipe_write(). When you are done, just call
- * ecore_pipe_del().
- *
- * For examples see here:
- * @li @ref tutorial_ecore_pipe_gstreamer_example
- * @li @ref tutorial_ecore_pipe_simple_example
- */
-
-
 /**
  * Create two file descriptors (sockets on Windows). Add
  * a callback that will be called when the file descriptor that
@@ -460,10 +443,6 @@ ecore_pipe_write(Ecore_Pipe *p, const void *buffer, unsigned int nbytes)
    return EINA_FALSE;
 }
 
-/**
- * @}
- */
-
 /**
  * @}
  */

legacy/ecore/src/lib/ecore/ecore_poll.c

@@ -191,21 +191,7 @@ _ecore_poller_cb_timer(void *data __UNUSED__)
 }
 
 /**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
-/**
- * @addtogroup Ecore_Poller_Group Ecore Poll functions
- *
- * These functions are for the need to poll information, but provide a shared
- * abstracted API to pool such polling to minimise wakeup and ensure all the
- * polling happens in as few spots as possible areound a core poll interval.
- * For now only 1 core poller type is supprted: ECORE_POLLER_CORE
- *
- * Example of @ref Ecore_Poller:
- * @li @ref ecore_poller_example_c
+ * @addtogroup Ecore_Poller_Group
  *
  * @{
  */
@@ -430,10 +416,6 @@ ecore_poller_del(Ecore_Poller *poller)
    return data;
 }
 
-/**
- * @}
- */
-
 /**
  * @}
  */

legacy/ecore/src/lib/ecore/ecore_throttle.c

@@ -10,12 +10,6 @@
 
 static int throttle_val = 0;
 
-/**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
 /**
  * @addtogroup Ecore_Throttle_Group Ecore Throttle functions
  *
@@ -92,10 +86,6 @@ ecore_throttle_get(void)
    return (double)throttle_val / 1000000.0;
 }
 
-/**
- * @}
- */
-
 /**
  * @}
  */

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

@@ -29,13 +29,7 @@ static double _ecore_time_clock_conversion = 1e-9;
 double _ecore_time_loop_time = -1.0;
 
 /**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
-
-/**
- * @addtogroup Ecore_Time_Group Ecore Time functions
+ * @addtogroup Ecore_Time_Group
  *
  * @{
  */
@@ -133,10 +127,6 @@ ecore_loop_time_get(void)
  * @}
  */
 
-/**
- * @}
- */
-
 
 /**********************   Internal methods   ********************************/
 

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

@@ -48,23 +48,9 @@ static Ecore_Timer *suspended = NULL;
 static double       last_check = 0.0;
 static double       precision = 10.0 / 1000000.0;
 
-/**
- * @addtogroup Ecore_Group Ecore - Main Loop and Job Functions.
- *
- * @{
- */
 
 /**
- * @addtogroup 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.
- *
- * The timer allows callbacks to be called at specific intervals.
- *
- * Examples with functions that deal with time:
- * @li @ref ecore_time_functions_example_c
- * @li @ref ecore_timer_example_c
+ * @addtogroup Ecore_Time_Group
  *
  * @{
  */
@@ -459,10 +445,6 @@ ecore_timer_dump(void)
 #endif
 }
 
-/**
- * @}
- */
-
 /**
  * @}
  */