ecore/doc - Move some examples to examples.dox

Also remove references to examples that don't exist anymore.

More examples are going to be explained, and removing them from Ecore.h
will improve the readability of that file. This is the same that was
done to Elementary.

I'm going to move all the examples reference to this file, and should
have them being pointed by functions that use them too.



SVN revision: 60598

legacy/ecore/doc/Doxyfile.in

@@ -74,7 +74,8 @@ WARN_NO_PARAMDOC       = YES
 WARN_FORMAT            = "$file:$line: $text"
 WARN_LOGFILE           =
 INPUT                  = @srcdir@/ecore.dox \
-                         @top_srcdir@/src/lib
+                         @top_srcdir@/src/lib \
+                         @srcdir@/examples.dox
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =
 RECURSIVE              = YES

legacy/ecore/doc/examples.dox

@@ -0,0 +1,50 @@
+/**
+ * @page Examples Examples
+ *
+ * Here is a page with some Ecore examples explained:
+ *
+ * @li @ref ecore_time_example_c
+ *
+ */
+
+/**
+ * @page ecore_time_example_c ecore_time - Differences between time functions
+ *
+ * This example shows the difference between calling ecore_time_get(),
+ * ecore_loop_time_get() and ecore_time_unix_get().
+ *
+ * It initializes ecore, then sets a timer with a callback that, when called,
+ * will retrieve the system time using these 3 different functions. After
+ * displaying the time, it sleeps for 1 second, then call display the time
+ * again using the 3 functions.
+ *
+ * Since everything occurs inside the same mainloop iteration, the internal
+ * ecore time variable will not be updated, and calling ecore_loop_time_get()
+ * before and after the sleep() call will return the same result.
+ *
+ * The two other functions will return a difference of 1 second, as expected.
+ * But ecore_time_unix_get() returns the number of seconds since 00:00:00 1st
+ * January 1970, while ecore_time_get() will return the time since a
+ * unspecified point, but that never goes back in time, even when the timezone
+ * of the machine changes.
+ *
+ * @note The usage of ecore_loop_time_get() should be preferred against the
+ * two other functions, for most time calculations, since it won't produce a
+ * system call to get the current time. Use ecore_time_unix_get() when you need
+ * to know the current time and date, and ecore_time_get() when you need a
+ * monotonic and more precise time than ecore_loop_time_get().
+ *
+ * @include ecore_time_example.c
+ */
+
+/**
+ * @example ecore_time_example.c
+ * Shows the difference between the three time functions. See @ref
+ * ecore_time_example_c "the example explained".
+ */
+
+/**
+ * @example ecore_fd_handler_example.c
+ * Shows how to use fd handlers.
+*/
+

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

@@ -70,6 +70,8 @@ The Ecore library provides the following modules:
 @li @ref Ecore_Win32_Group
 @li @ref Ecore_WinCE_Group
 
+For more info on Ecore usage, there are these @ref Examples.
+
 @section compiling How to compile using Ecore?
 pkgconfig (.pc) files are installed for every ecore module.
 Thus, to compile using any of them, you can use something like the following:
@@ -246,44 +248,6 @@ This page briefly explains what the X window system is and various terms
 that are used.
 */
 
-// EXAMPLES
-
-/**
-@example ecore_args_example.c
-Shows how to set and retrieve the program arguments.
-*/
-
-/**
-@example ecore_event_handler_example.c
-Shows how to use event handlers.
-*/
-
-/**
-@example ecore_fd_handler_example.c
-Shows how to use fd handlers.
-*/
-
-/**
-@example ecore_timer_example.c
-Demonstrates use of the ecore_timer.
-*/
-
-/*
-@example ecore_config_basic_example.c
-Provides an example of how to use the basic configuration functions.
-See the file Ecore_Config.h for the full list of available functions.
-*/
-
-/*
-@example ecore_config_listener_example.c
-Shows how to set up a listener to listen for configuration changes.
-*/
-
-/**
-@example ecore_x_window_example.c
-Shows the basics of using the X Windows system through Ecore functions.
-*/
-
 #ifndef _ECORE_H
 #define _ECORE_H
 
@@ -838,31 +802,6 @@ extern "C" {
    * @}
    */
 
-  /**
-   * @page ecore_time_example_c ecore_time - Differences between time functions
-   *
-   * This example shows the difference between calling ecore_time_get(),
-   * ecore_loop_time_get() and ecore_time_unix_get().
-   *
-   * It initializes ecore, then sets a timer with a callback that, when called,
-   * will retrieve the system time using these 3 different functions. After
-   * displaying the time, it sleeps for 1 second, then call display the time
-   * again using the 3 functions.
-   *
-   * Since everything occurs inside the same mainloop iteration, the internal
-   * ecore time variable will not be updated, and calling ecore_loop_time_get()
-   * before and after the sleep() call will return the same result.
-   *
-   * The two other functions will return a difference of 1 second, as expected.
-   *
-   * @note The usage of ecore_loop_time_get() should be preferred against the
-   * two other functions, since it won't produce a system call to get the
-   * current time.
-   *
-   * @include ecore_time_example.c
-   * @example ecore_time_example.c
-   */
-
   /**
    * @defgroup Ecore_Time_Group Ecore Time functions
    *

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

@@ -54,8 +54,6 @@ double _ecore_time_loop_time = -1.0;
  *         when the machine was booted, unix time, etc), all it is
  *         defined is that it never goes backwards (unless you got big critical
  *         messages when the application started).
- *
- * @see @ref ecore_time_example_c
  */
 EAPI double
 ecore_time_get(void)
@@ -90,8 +88,6 @@ ecore_time_get(void)
  * @see ecore_loop_time_get().
  *
  * @return  The number of seconds since 12.00AM 1st January 1970.
- *
- * @see @ref ecore_time_example_c
  */
 EAPI double
 ecore_time_unix_get(void)
@@ -126,8 +122,6 @@ ecore_time_unix_get(void)
  *         when the machine was booted, unix time, etc), all it is
  *         defined is that it never goes backwards (unless you got big critical
  *         messages when the application started).
- *
- * @see @ref ecore_time_example_c
  */
 EAPI double
 ecore_loop_time_get(void)