efl/docs: clean-up and make it more uniform.

now unified docs are bit more uniform in their start pages, overall
improved but much to do :-(



SVN revision: 81851

doc/Doxyfile.in

@@ -594,11 +594,14 @@ WARN_LOGFILE           =
 
 INPUT                  = @top_srcdir@/src/lib \
                          @srcdir@/main.dox \
+                         @srcdir@/pkgconfig.dox \
+                         @srcdir@/eina_examples.dox \
                          @srcdir@/ecore_examples.dox \
                          @srcdir@/eet_examples.dox \
                          @srcdir@/evas_examples.dox \
                          @srcdir@/eo_tutorial.dox \
-                         @srcdir@/eio_examples.dox
+                         @srcdir@/eio_examples.dox \
+                         @srcdir@/edbus_examples.dox
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
@@ -794,12 +797,16 @@ COLS_IN_ALPHA_INDEX    = 2
 # The IGNORE_PREFIX tag can be used to specify one or more prefixes that
 # should be ignored while generating the index headers.
 
-IGNORE_PREFIX          = eina_ \
-                         _eina_ \
-                         Eina_ \
-                         _Eina_ \
-                         EINA_ \
-                         _EINA_
+IGNORE_PREFIX          = eina_ _eina_ Eina_ _Eina_ EINA_ _EINA_ \
+eo_ _eo_ Eo_ _Eo_ EO_ _EO_ \
+embryo_ _embryo_ Embryo_ _Embryo_ EMBRYO_ _EMBRYO_ \
+escape_ _escape_ Escape_ _Escape_ ESCAPE_ _ESCAPE_ \
+evil_ _evil_ Evil_ _Evil_ EVIL_ _EVIL_ \
+evas_ _evas_ Evas_ _Evas_ EVAS_ _EVAS_ \
+eet_ _eet_ Eet_ _Eet_ EET_ _EET_ \
+ecore_ _ecore_ Ecore_ _Ecore_ ECORE_ _ECORE_ \
+eio_ _eio_ Eio_ _Eio_ EIO_ _EIO_ \
+edbus_ _edbus_ EDBus_ _EDBus_ EDBUS_ _EDBUS_
 
 #---------------------------------------------------------------------------
 # configuration options related to the HTML output

doc/edbus_examples.dox

@@ -0,0 +1,45 @@
+/**
+ * @page edbus_examples EDBus Examples
+ *
+ * Examples:
+ * @li @ref banshee.c
+ * @li @ref client.c
+ * @li @ref complex-types.c
+ * @li @ref complex-types-client-eina-value.c
+ * @li @ref complex-types-server.c
+ * @li @ref connman-list-services.c
+ * @li @ref ofono-dial.c
+ * @li @ref server.c
+ * @li @ref simple-signal-emit.c
+ *
+ * @example banshee.c
+ * Access Banshee music player and send commands to it.
+ *
+ * @example client.c
+ * Client to test various call message types against a provided server
+ * (@ref server.c)
+ *
+ * @example complex-types.c
+ * Client to test complex types (arrays, structs, dicts) against a
+ * provided server (@ref complex-types-server.c)
+ *
+ * @example complex-types-client-eina-value.c
+ * Client to test complex types (arrays, structs, dicts) against a
+ * provided server (@ref complex-types-server.c) returning them as
+ * @ref Eina_Value.
+ *
+ * @example complex-types-server.c
+ * Server to test complex types (arrays, structs, dicts).
+ *
+ * @example connman-list-services.c
+ * Client to list networks/services from connman.
+ *
+ * @example ofono-dial.c
+ * Client to ask oFono to dial.
+ *
+ * @example server.c
+ * Server to reply to @ref client.c requests.
+ *
+ * @example simple-signal-emit.c
+ * Server that registers a service interface and emits simple signals.
+ */

doc/eet_examples.dox

@@ -12,8 +12,6 @@
  * @ref Example_Eet_Data_File_Descriptor_02
  *
  * @ref Example_Eet_Data_Cipher_Decipher
- *
- * <a href="examples.html">List of examples</a>
  */
 
 /**

doc/eina_examples.dox

@@ -0,0 +1,105 @@
+/**
+ * @page eina_examples Eina Examples
+ *
+ * Examples:
+ * @li @ref eina_accessor_01.c
+ * @li @ref eina_array_01.c
+ * @li @ref eina_array_02.c
+ * @li @ref eina_error_01.c
+ * @li @ref eina_file_01.c
+ * @li @ref eina_hash_01.c
+ * @li @ref eina_hash_02.c
+ * @li @ref eina_hash_03.c
+ * @li @ref eina_hash_04.c
+ * @li @ref eina_hash_05.c
+ * @li @ref eina_hash_06.c
+ * @li @ref eina_hash_07.c
+ * @li @ref eina_hash_08.c
+ * @li @ref eina_inarray_01.c
+ * @li @ref eina_inarray_02.c
+ * @li @ref eina_inlist_01.c
+ * @li @ref eina_inlist_02.c
+ * @li @ref eina_inlist_03.c
+ * @li @ref eina_iterator_01.c
+ * @li @ref eina_list_01.c
+ * @li @ref eina_list_02.c
+ * @li @ref eina_list_03.c
+ * @li @ref eina_list_04.c
+ * @li @ref eina_log_01.c
+ * @li @ref eina_log_02.c
+ * @li @ref eina_log_03.c
+ * @li @ref eina_magic_01.c
+ * @li @ref eina_model_01.c
+ * @li @ref eina_model_02.c
+ * @li @ref eina_model_03.c
+ * @li @ref eina_model_04_animal.c
+ * @li @ref eina_model_04_child.c
+ * @li @ref eina_model_04_human.c
+ * @li @ref eina_model_04_main.c
+ * @li @ref eina_model_04_parrot.c
+ * @li @ref eina_model_04_whistler.c
+ * @li @ref eina_simple_xml_parser_01.c
+ * @li @ref eina_str_01.c
+ * @li @ref eina_strbuf_01.c
+ * @li @ref eina_stringshare_01.c
+ * @li @ref eina_tiler_01.c
+ * @li @ref eina_value_01.c
+ * @li @ref eina_value_02.c
+ * @li @ref eina_value_03.c
+ *
+ * Tutorials:
+ * @li @ref tutorial_benchmark_page
+ * @li @ref tutorial_binshare_page
+ * @li @ref tutorial_eina_string
+ * @li @ref tutorial_error_page
+ * @li @ref tutorial_log_page
+ * @li @ref tutorial_matrixsparse_page
+ * @li @ref tutorial_quadtree_page
+ * @li @ref tutorial_strbuf
+ * @li @ref tutorial_ustringshare_page
+ *
+ * @example eina_accessor_01.c
+ * @example eina_array_01.c
+ * @example eina_array_02.c
+ * @example eina_error_01.c
+ * @example eina_file_01.c
+ * @example eina_hash_01.c
+ * @example eina_hash_02.c
+ * @example eina_hash_03.c
+ * @example eina_hash_04.c
+ * @example eina_hash_05.c
+ * @example eina_hash_06.c
+ * @example eina_hash_07.c
+ * @example eina_hash_08.c
+ * @example eina_inarray_01.c
+ * @example eina_inarray_02.c
+ * @example eina_inlist_01.c
+ * @example eina_inlist_02.c
+ * @example eina_inlist_03.c
+ * @example eina_iterator_01.c
+ * @example eina_list_01.c
+ * @example eina_list_02.c
+ * @example eina_list_03.c
+ * @example eina_list_04.c
+ * @example eina_log_01.c
+ * @example eina_log_02.c
+ * @example eina_log_03.c
+ * @example eina_magic_01.c
+ * @example eina_model_01.c
+ * @example eina_model_02.c
+ * @example eina_model_03.c
+ * @example eina_model_04_animal.c
+ * @example eina_model_04_child.c
+ * @example eina_model_04_human.c
+ * @example eina_model_04_main.c
+ * @example eina_model_04_parrot.c
+ * @example eina_model_04_whistler.c
+ * @example eina_simple_xml_parser_01.c
+ * @example eina_str_01.c
+ * @example eina_strbuf_01.c
+ * @example eina_stringshare_01.c
+ * @example eina_tiler_01.c
+ * @example eina_value_01.c
+ * @example eina_value_02.c
+ * @example eina_value_03.c
+ */

doc/eo_tutorial.dox

@@ -1,12 +1,10 @@
 /**
  * @page Eo_Tutorial Eo Tutorial
  *
- * Purpose:
- * -------
+ * @section Purpose
  * The purpose of this document is to explain how to work with Eo, how to port your code to Eo and what are the common pitfalls. It doesn't explain how it works inside.
  *
- * Description:
- * -----------
+ * @section Description
  * Eo is an Object oriented infrastructure for the EFL. It is a API/ABI safe library.
  * 
  * It supports inheritance, mixins, interfaces and composite objects.\n
@@ -16,10 +14,9 @@
  * At the creation of the class, a "virtual table" is filled with the needed functions.\n
  * The key of this table is a (class id, function id) tuple.
  * 
- * eo_do is invoked with a list of op ids and their parameters and is in charge to dispatch the relevant functions. Finding the correct function is fast because it is just a lookup table.
+ * eo_do() is invoked with a list of op ids and their parameters and is in charge to dispatch the relevant functions. Finding the correct function is fast because it is just a lookup table.
  *
- * How to use it?
- * -------------
+ * @section How to use it?
  * - Creation of an instance of a class
  *
  *   - Old way:
@@ -74,18 +71,17 @@
  *    eo_do_super(obj, elm_wdg_theme(&int_ret));
  * @endcode
  *
- * Important to know:
- * -----------------
- * - eo_do is the function used to invoke functions of a specific class on an object.
+ * @section Important to know
+ * - eo_do() is the function used to invoke functions of a specific class on an object.
  * 
- * - eo_data_get receives an object and a class and returns the data of the given class for the object. The class must belong to the object class hierarchy.
+ * - eo_data_get() receives an object and a class and returns the data of the given class for the object. The class must belong to the object class hierarchy.
  * 
- * - eo_isa indicates if a given object is of a given type.
+ * - eo_isa() indicates if a given object is of a given type.
  * 
- * - eo_do_super is in charge to invoke a function in the next parents that implement it. It is recommended to use eo_do_super only from a function with the same op id.\n
+ * - eo_do_super() is in charge to invoke a function in the next parents that implement it. It is recommended to use eo_do_super() only from a function with the same op id.\n
  * In addition, there is no way to jump over classes who implement the function. If A inherits from B, B from C and A, B and C implement a virtual function defined in C, the function calls order will be A, then B and finally C. It is impossible to pass over B.
  * 
- * - eo_do returns if the operation succeeded or failed (function found, object deleted...), not the result of the called function. Pay attention to this detail when you call eo_do. The return value needs to be an additional parameter which will hold a return value.
+ * - eo_do() returns if the operation succeeded or failed (function found, object deleted...), not the result of the called function. Pay attention to this detail when you call eo_do(). The return value needs to be an additional parameter which will hold a return value.
  * 
  * - Don't do this:
  * @code
@@ -95,12 +91,12 @@
  *          evas_obj_size_set(w+10, h+20));
  * @endcode
  *    w+10 and h+20 are evaluated before the call to size_get.
- *    Instead, separate it in two calls to eo_do.
+ *    Instead, separate it in two calls to eo_do().
  * 
- * - When creating an object with eo_add, the reference counter of this one is incremented. If it is called with a parent, two references are on the object. eo_del removes both of these references.\n
- * When there is no more references on an object, this one is deleted and then can be freed. The deletion calls to the destructor (see eo_destructor). When done, Eo checks if the object can be freed. The free mechanism can be "disabled" through eo_manual_free_set. If this is the case, it is the responsibility of the developer to call eo_manual_free on the object in order to free it. This mechanism has been used for example in Evas on the Evas objects and in Ecore.
+ * - When creating an object with eo_add(), the reference counter of this one is incremented. If it is called with a parent, two references are on the object. eo_del() removes both of these references.\n
+ * When there is no more references on an object, this one is deleted and then can be freed. The deletion calls to the destructor (see eo_destructor()). When done, Eo checks if the object can be freed. The free mechanism can be "disabled" through eo_manual_free_set(). If this is the case, it is the responsibility of the developer to call eo_manual_free() on the object in order to free it. This mechanism has been used for example in @ref Evas on the Evas objects and in @ref Ecore.
  * 
- * - When eo_do reaches a function of a class, it is the responsibility of the user to extract from the va_list ALL the parameters needed for this function, NO MORE, NO LESS. Otherwise, unknown behavior can occur. eo_do is called with a list of op id, params, op id, params... A bad extraction of parameters can bring to the parsing of a wrong op id and so in the best case, to an error, in the worst case, to another function not in relation with the actual use case.
+ * - When eo_do() reaches a function of a class, it is the responsibility of the user to extract from the va_list ALL the parameters needed for this function, NO MORE, NO LESS. Otherwise, unknown behavior can occur. eo_do() is called with a list of op id, params, op id, params... A bad extraction of parameters can bring to the parsing of a wrong op id and so in the best case, to an error, in the worst case, to another function not in relation with the actual use case.
  * 
  * - Always pay attention to:
  *    - the pairing between function id and the function itself. Using the same function for two ids occurs and is hard to debug.
@@ -111,8 +107,7 @@
  * 
  * - Avoid exposing your class data to prevent ABI break. Supply access functions instead.
  *
- * How to create a class - H side?
- * ------------------------------
+ * @section How to create a class - H side?
  * - If the object is new, establish the public APIs
  * - #define \$(CLASS_NAME) \$(class_name)_class_get(): will be used to access data/inherit from this class...
  * - const Eo_Class *\$(class_name)_class_get(void) EINA_CONST: declaration of the function that will create the class (not the instance), i.e virtual table...
@@ -172,8 +167,7 @@
  * #define evas_obj_line_xy_get(x1, y1, x2, y2) EVAS_OBJ_LINE_ID(EVAS_OBJ_LINE_SUB_ID_XY_GET), EO_TYPECHECK(Evas_Coord *, x1), EO_TYPECHECK(Evas_Coord *, y1), EO_TYPECHECK(Evas_Coord *, x2), EO_TYPECHECK(Evas_Coord *, y2)
    @endcode
  *
- * How to create a class - C side?
- * ------------------------------
+ * @section How to create a class - C side?
  * Below, the object line as example.
  * 
  * #include "Eo.h"\n
@@ -198,8 +192,8 @@
  * }
  * @endcode
  * 
- * You can (not a must) implement a constructor. This constructor MUST call the parent constructor (eo_do_super). It is the same for the destructor.\n
- * See eo_constructor and eo_destructor.\n
+ * You can (not a must) implement a constructor. This constructor MUST call the parent constructor (eo_do_super()). It is the same for the destructor.\n
+ * See eo_constructor() and eo_destructor().\n
  * If you don't have anything to do in constructor (like malloc, variables init...) or in destructor (free), don't implement them.
  * 
  * At the end of the file, you need to describe the class.\n

doc/head.html

@@ -50,10 +50,14 @@
     <div class="menu-container">
         <div class="submenu">
             <ul class="current">
+                <li><a href="authors.html">Authors</a></li>
+                <li><a href="examples.html">Examples</a></li>
                 <li><a href="files.html">Files</a></li>
+                <li><a href="pages.html">Pages</a></li>
+                <li>|</li>
+                <li><a href="classes.html">Types</a></li>
                 <li><a href="modules.html">Modules</a></li>
-                <li><a href="pages.html">Related Pages</a></li>
-	        <li class="current"><a  href="index.html">Main Page</a></li>
+	        <li><a  href="index.html">Main Page</a></li>
             </ul>
         </div>
     </div>

doc/main.dox

@@ -7,15 +7,16 @@
  * find documentation auto-generated daily from SVN source for these
  * libraries:
  *
- * @li @ref eina_main
- * @li @ref evas_main
- * @li @ref eet_main
- * @li @ref embryo_main
- * @li @ref ecore_main
- * @li @ref escape_main
- * @li @ref evil_main
- * @li @ref eio_main
- * @li @ref edbus_main
+ * @li @ref eina_main data types and low-level/basic abstractions.
+ * @li @ref eo_main generic object system.
+ * @li @ref evas_main drawing canvas.
+ * @li @ref eet_main binary data parser and serializer.
+ * @li @ref embryo_main embedded script language.
+ * @li @ref ecore_main operating system abstraction and integration.
+ * @li @ref escape_main playstation3 portability layer.
+ * @li @ref evil_main microsoft windows portability layer.
+ * @li @ref eio_main asynchronous input/output
+ * @li @ref edbus_main d-bus integration.
  *
  */
 
@@ -117,56 +118,62 @@
  *
  */
 
+/**
+ * @defgroup Eo
+ *
+ * @brief Generic object system.
+ */
+
 /**
  * @defgroup Evas
  *
- * @brief Evas
+ * @brief Drawing canvas.
  */
 
 /**
  * @defgroup Eet
  *
- * @brief Eet
+ * @brief Binary data parser and serializer.
  */
 
 /**
  * @defgroup Eina
  *
- * @brief Eina
+ * @brief Data types and low-level/basic abstractions.
  */
 
 /**
  * @defgroup Embryo
  *
- * @brief Embryo
+ * @brief Embedded script language.
  */
 
 /**
  * @defgroup Evil
  *
- * @brief Evil
+ * @brief Microsoft Windows portability layer.
  */
 
 /**
  * @defgroup Escape
  *
- * @brief Escape
+ * @brief PlayStation3 portability layer.
  */
 
 /**
  * @defgroup Ecore
  *
- * @brief Ecore
+ * @brief Operating System Abstraction and Integration.
  */
 
 /**
  * @defgroup Eio
  *
- * @brief Eio
+ * @brief Asynchronous input/output and file manipulation.
  */
 
 /**
  * @defgroup EDBus
  *
- * @brief EDBus
+ * @brief D-Bus integration with EFL (Ecore).
  */

doc/pkgconfig.dox

@@ -0,0 +1,61 @@
+/**
+   @page pkgconfig
+
+   @section pkgconfig_intro Introduction
+
+   pkg-config (http://pkgconfig.freedesktop.org/wiki/) is a helper
+   tool used when compiling applications and libraries. It helps you
+   insert the correct compiler options on the command line based on
+   installed software, instead of hard-coded values.
+
+   @section pkgconfig_usage Usage
+
+   Using pkg-config it is as simple as:
+   @verbatim
+   # compile:
+   gcc -c -o main.o main.c `pkg-config --cflags PKGNAME`
+
+   # link:
+   gcc -o my_application main.o `pkg-config --libs PKGNAME`
+
+   # compile + link in a single step:
+   gcc -o my_application main.c `pkg-config --cflags --libs PKGNAME`
+   @endverbatim
+
+   Where @b PKGNAME is your module, such as eina, eet, evas, ecore,
+   ecore-x, eio and so on.
+
+   One can do some queries such as the module version, other variables:
+   @verbatim
+   pkg-config --modversion PKGNAME
+   pkg-config --variable=prefix PKGNAME
+   @endverbatim
+
+   @section pkgconfig_troubleshooting Troubleshooting
+
+   Make sure @c pkg-config command is in your @c $PATH, otherwise
+   you'll end with:
+
+   @verbatim
+   pkg-config: command not found
+   @endverbatim
+
+   The @b PKGNAME it searched using pkg-config's build location,
+   usually @c /usr/lib/pkgconfig. This can be overwritten with @c
+   $PKG_CONFIG_LIBDIR (usually for cross compile) or extended with @c
+   $PKG_CONFIG_PATH. If you installed EFL to @c /opt/efl, then use:
+
+   @verbatim
+   export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/opt/efl/lib/pkgconfig"
+   pkg-config --cflags --libs PKGNAME
+   @endverbatim
+
+   Otherwise you'll end with:
+   @verbatim
+   Package PKGNAME was not found in the pkg-config search path.
+   Perhaps you should add the directory containing `PKGNAME.pc'
+   to the PKG_CONFIG_PATH environment variable
+   No package 'PKGNAME' found
+   @endverbatim
+
+*/

src/lib/ecore/Ecore.h

@@ -8,10 +8,14 @@
 
    @page ecore_main Ecore
 
-   @version 1.7
-   @date 2000-2012
+   @date 2000 (created)
 
-   Please see the @ref authors page for contact details.
+   @section toc Table of Contents
+
+   @li @ref ecore_main_intro
+   @li @ref ecore_main_compiling
+   @li @ref ecore_main_next_steps
+   @li @ref ecore_main_intro_example
 
    @section ecore_main_intro Introduction
 
@@ -36,35 +40,49 @@
 
    For more info on Ecore usage, there are these @ref ecore_examples.
 
-   @section ecore_main_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:
-
-@verbatim
-gcc *.c $(pkg-config ecore ecore-$x ecore-$y [...] --cflags --libs)
-@endverbatim
-
-   @section ecore_main_install How is it installed?
-
-   Suggested configure options for ecore for a Linux desktop X display
-   with OpenGL and Software support, communication (networking) and
-   IPC (inter process communication):
-
-@verbatim
-./configure \
-    --enable-ecore-con \
-    --enable-ecore-ipc \
-    --enable-ecore-file \
-    --enable-ecore-input \
-    --enable-ecore-input-evas \
-    --enable-ecore-x \
-    --enable-ecore-evas \
-    --enable-ecore-evas-software-buffer \
-    --enable-ecore-evas-software-x11 \
-    --enable-ecore-evas-opengl-x11
-make
-sudo make install
-@endverbatim
+   @section ecore_main_compiling How to compile
+
+   Ecore is a library your application links to. The procedure for
+   this is very simple. You simply have to compile your application
+   with the appropriate compiler flags that the @p pkg-config script
+   outputs. Note that each module is separate in pkg-config. For
+   example using @ref Ecore_Evas_Group:
+
+   Compiling C or C++ files into object files:
+
+   @verbatim
+   gcc -c -o main.o main.c `pkg-config --cflags ecore ecore-evas`
+   @endverbatim
+
+   Linking object files into a binary executable:
+
+   @verbatim
+   gcc -o my_application main.o `pkg-config --libs ecore ecore-evas`
+   @endverbatim
+
+   See @ref pkgconfig
+
+   @section ecore_main_next_steps Next Steps
+
+   After you understood what Ecore is and installed it in your system
+   you should proceed understanding the programming interface. We'd
+   recommend you to take a while to learn @ref Eina as it is very
+   convenient and optimized, and Ecore uses it extensively.
+
+   Recommended reading:
+
+   @li @ref Ecore_Timer_Group
+   @li @ref Ecore_Idle_Group
+   @li @ref Ecore_FD_Handler_Group
+   @li @ref Ecore_Event_Group
+   @li @ref Ecore_Exe_Group
+
+   @section ecore_main_intro_example Introductory Examples
+
+   @include ecore_timer_example.c
+
+   More examples can be found at @ref ecore_examples.
+
 
  */
 

src/lib/edbus/EDBus.h

@@ -1,14 +1,23 @@
 /**
  * @page edbus_main EDBus
  *
- * @section edbus_intro_sec Introduction
+ * @date 2012 (created)
+ *
+ * @section toc Table of Contents
+ *
+ * @li @ref edbus_main_intro
+ * @li @ref edbus_main_compiling
+ * @li @ref edbus_main_next_steps
+ * @li @ref edbus_main_intro_example
+ *
+ * @section edbus_main_intro Introduction
  *
  * EDBus is a wrapper around the
  * <a href="http://www.freedesktop.org/wiki/Software/dbus">dbus</a>
  * library, which is a message bus system. It also implements a set of
  * specifications using dbus as interprocess communication.
  *
- * @section edbus_modules_sec Modules
+ * @subsection edbus_modules_sec Modules
  *
  * <ul>
  * <li> @ref EDBus_Core
@@ -27,50 +36,42 @@
  * <li> @ref EDBus_Basic
  * </ul>
  *
- * @section edbus_examples_sec Examples
+ * @section edbus_main_compiling How to compile
+ *
+ * EDBus is a library your application links to. The procedure for this is
+ * very simple. You simply have to compile your application with the
+ * appropriate compiler flags that the @c pkg-config script outputs. For
+ * example:
  *
- * Here some EDBus examples:
+ * Compiling C or C++ files into object files:
  *
- * @li @ref banshee.c
- * @li @ref client.c
- * @li @ref complex-types.c
- * @li @ref complex-types-client-eina-value.c
- * @li @ref complex-types-server.c
- * @li @ref connman-list-services.c
- * @li @ref ofono-dial.c
- * @li @ref server.c
- * @li @ref simple-signal-emit.c
+ * @verbatim
+   gcc -c -o main.o main.c `pkg-config --cflags edbus2`
+   @endverbatim
  *
- * @example banshee.c
- * Access Banshee music player and send commands to it.
+ * Linking object files into a binary executable:
  *
- * @example client.c
- * Client to test various call message types against a provided server
- * (@ref server.c)
+ * @verbatim
+   gcc -o my_application main.o `pkg-config --libs edbus2`
+   @endverbatim
  *
- * @example complex-types.c
- * Client to test complex types (arrays, structs, dicts) against a
- * provided server (@ref complex-types-server.c)
+ * See @ref pkgconfig
  *
- * @example complex-types-client-eina-value.c
- * Client to test complex types (arrays, structs, dicts) against a
- * provided server (@ref complex-types-server.c) returning them as
- * @ref Eina_Value.
+ * @section edbus_main_next_steps Next Steps
  *
- * @example complex-types-server.c
- * Server to test complex types (arrays, structs, dicts).
+ * After you understood what EDBus is and installed it in your system
+ * you should proceed understanding the programming interface.
  *
- * @example connman-list-services.c
- * Client to list networks/services from connman.
+ * Recommended reading:
+ * @li @ref EDBus_Core for library init, shutdown and getting a connection.
+ * @li @ref EDBus_Proxy to easily bind a client object to an interface.
+ * @li @ref EDBus_Object_Mapper to monitor server objects and properties.
  *
- * @example ofono-dial.c
- * Client to ask oFono to dial.
+ * @section edbus_main_intro_example Introductory Example
  *
- * @example server.c
- * Server to reply to @ref client.c requests.
+ * @include ofono-dial.c
  *
- * @example simple-signal-emit.c
- * Server that registers a service interface and emits simple signals.
+ * More examples can be found at @ref edbus_examples.
  */
 #ifndef EDBUS_H
 #define EDBUS_H

src/lib/eet/Eet.h

@@ -3,23 +3,18 @@
 
    These routines are used for Eet Library interaction
 
-   @page eet_main Eet Library Documentation
+   @page eet_main Eet
 
-   @version 1.7.0
-   @date 2000-2012
-
-   Please see the @ref authors page for contact details.
+   @date 2000 (created)
 
    @section toc Table of Contents
 
    @li @ref eet_main_intro
-   @li @ref eet_main_example
    @li @ref eet_main_compiling
-   @li @ref eet_main_install
    @li @ref eet_main_next_steps
    @li @ref eet_main_intro_example
 
-   @section eet_main_intro What is Eet?
+   @section eet_main_intro Introduction
 
    It is a tiny library designed to write an arbitrary set of chunks of data
    to a file and optionally compress each chunk (very much like a zip file)
@@ -40,23 +35,7 @@
    encoded in a platform independent way and can be written and read by any
    architecture.
 
-   @section eet_main_example A simple example on using Eet
-
-   Here is a simple example on how to use Eet to save a series of strings to a
-   file and load them again. The advantage of using Eet over just
-   fprintf() and
-   fscanf() is that not only can these entries be strings, they need no special
-   parsing to handle delimiter characters or escaping, they can be binary data,
-   image data, data structures containing integers, strings, other data
-   structures, linked lists and much more, without the programmer having to
-   worry about parsing, and best of all, Eet is very fast.
-
-   This is just a very simple example that doesn't show all of the capabilities
-   of Eet, but it serves to illustrate its simplicity.
-
-   @include eet-basic.c
-
-   @section eet_main_compiling How to compile using Eet ?
+   @section eet_main_compiling How to compile
 
    Eet is a library your application links to. The procedure for this is very
    simple. You simply have to compile your application with the appropriate
@@ -74,38 +53,14 @@
    gcc -o my_application main.o `pkg-config --libs eet`
    @endverbatim
 
-   You simply have to make sure that pkg-config is in your shell's PATH (see
-   the manual page for your appropriate shell) and eet.pc in /usr/lib/pkgconfig
-   or its path is in the PKG_CONFIG_PATH environment variable. It's that simple
-   to link and use Eet once you have written your code to use it.
-
-   Since the program is linked to Eet, it is now able to use any advertised
-   API calls to serialize your data.
-
-   You should make sure you add any extra compile and link flags to your
-   compile commands that your application may need as well. The above example
-   is only guaranteed to make Eet add it's own requirements.
-
-
-   @section eet_main_install How is it installed?
-
-   Simple:
-
-   @verbatim
-   ./configure
-   make
-   su -
-   ...
-   make install
-   @endverbatim
+   See @ref pkgconfig
 
    @section eet_main_next_steps Next Steps
 
-   After you understood what Eet is and installed it in your system you
-   should proceed understanding the programming interface. We'd recommend
-   you to take a while to learn Eina
-   (http://docs.enlightenment.org/auto/eina/) as it is very convenient
-   and optimized, and Eet provides integration with it.
+   After you understood what Eet is and installed it in your system
+   you should proceed understanding the programming interface. We'd
+   recommend you to take a while to learn @ref Eina as it is very
+   convenient and optimized, and Eet provides integration with it.
 
    Recommended reading:
 
@@ -116,7 +71,21 @@
 
    @section eet_main_intro_example Introductory Examples
 
-   @ref eet_examples
+   Here is a simple example on how to use Eet to save a series of strings to a
+   file and load them again. The advantage of using Eet over just
+   fprintf() and
+   fscanf() is that not only can these entries be strings, they need no special
+   parsing to handle delimiter characters or escaping, they can be binary data,
+   image data, data structures containing integers, strings, other data
+   structures, linked lists and much more, without the programmer having to
+   worry about parsing, and best of all, Eet is very fast.
+
+   This is just a very simple example that doesn't show all of the capabilities
+   of Eet, but it serves to illustrate its simplicity.
+
+   @include eet-basic.c
+
+   More examples can be found at @ref eet_examples.
 
    @todo Document data format for images and data structures.
 

src/lib/eina/Eina.h

@@ -46,10 +46,16 @@
 /**
  * @page eina_main Eina
  *
- * @version 1.7
- * @date 2008-2012
+ * @date 2008 (created)
  *
- * @section eina_intro_sec Introduction
+ * @section toc Table of Contents
+ *
+ * @li @ref eina_main_intro
+ * @li @ref eina_main_compiling
+ * @li @ref eina_main_next_steps
+ * @li @ref eina_main_intro_example
+ *
+ * @section eina_main_intro Introduction
  *
  * The Eina library is a library that implements an API for data types
  * in an efficient way. It also provides some useful tools like
@@ -90,8 +96,45 @@
  * @li @ref Eina_Rectangle_Group rectangle structure and standard manipulation methods.
  * @li @ref Eina_Safety_Checks_Group extra checks that will report unexpected conditions and can be disabled at compile time.
  * @li @ref Eina_String_Group a set of functions that manages C strings.
- * 
- * Please see the @ref authors page for contact details.
+ *
+ * @section eina_main_compiling How to compile
+ *
+ * Eina is a library your application links to. The procedure for this is
+ * very simple. You simply have to compile your application with the
+ * appropriate compiler flags that the @c pkg-config script outputs. For
+ * example:
+ *
+ * Compiling C or C++ files into object files:
+ *
+ * @verbatim
+   gcc -c -o main.o main.c `pkg-config --cflags eina`
+   @endverbatim
+ *
+ * Linking object files into a binary executable:
+ *
+ * @verbatim
+   gcc -o my_application main.o `pkg-config --libs eina`
+   @endverbatim
+ *
+ * See @ref pkgconfig
+ *
+ * @section eina_main_next_steps Next Steps
+ *
+ * After you understood what Eina is and installed it in your system
+ * you should proceed understanding the programming interface.
+ *
+ * Recommended reading:
+ *
+ * @li @ref Eina_Data_Types_Group to find about implemented types and
+ *     how to use them.
+ * @li @ref Eina_Tools_Group to find about helper tools provided by eina.
+ *
+ * @section eina_main_intro_example Introductory Example
+ *
+ * @include eina_list_01.c
+ *
+ * More examples can be found at @ref eina_examples.
+ *
  *
  * @defgroup Eina_Data_Types_Group Data Types
  * @ingroup Eina

src/lib/eio/Eio.h

@@ -87,7 +87,16 @@ extern "C" {
 /**
  * @page eio_main Eio
  *
- * @section eio_intro_sec Introduction
+ * @date 2012 (created)
+ *
+ * @section toc Table of Contents
+ *
+ * @li @ref eio_main_intro
+ * @li @ref eio_main_compiling
+ * @li @ref eio_main_next_steps
+ * @li @ref eio_main_intro_example
+ *
+ * @section eio_main_intro Introduction
  *
  * The Eio library is a library that implements an API for asynchronous
  * input/output operation. Most operation are done in a separated thread
@@ -101,9 +110,45 @@ extern "C" {
  * Linux, BSD, Opensolaris and Windows (XP and CE). It is heavily
  * based on @ref Ecore_Main_Loop_Group.
  *
- * @section eio_main_intro_example Introductory Examples
+ * @section eio_main_compiling How to compile
+ *
+ * Eio is a library your application links to. The procedure for this is
+ * very simple. You simply have to compile your application with the
+ * appropriate compiler flags that the @c pkg-config script outputs. For
+ * example:
+ *
+ * Compiling C or C++ files into object files:
+ *
+ * @verbatim
+   gcc -c -o main.o main.c `pkg-config --cflags eio`
+   @endverbatim
+ *
+ * Linking object files into a binary executable:
+ *
+ * @verbatim
+   gcc -o my_application main.o `pkg-config --libs eio`
+   @endverbatim
+ *
+ * See @ref pkgconfig
+ *
+ * @section eio_main_next_steps Next Steps
+ *
+ * After you understood what Eio is and installed it in your system
+ * you should proceed understanding the programming interface.
+ *
+ * Recommended reading:
+ *
+ * @li @ref Eio_Helper for common functions and library initialization.
+ * @li @ref Eio_Map to manipulate files asynchronously (mmap).
+ * @li @ref Eio_Xattr to access file extended attributes (xattr).
+ * @li @ref Eio_Monitor to monitor for file changes (inotify).
+ * @li @ref Eio_Eet to access Eet files asynchronously.
+ *
+ * @section eio_main_intro_example Introductory Example
+ *
+ * @include eio_file_ls.c
  *
- * @ref eio_examples
+ * More examples can be found at @ref eio_examples.
  *
  * @{
  */

src/lib/embryo/Embryo.h

@@ -3,16 +3,18 @@
  
 These routines are used for Embryo.
 
-@page embryo_main Embryo Library Documentation
+@page embryo_main Embryo
 
-@image html  e_big.png
+@date 2004 (created)
+@note based on Compuphase (http://www.compuphase.com) PAWN language.
 
-@version 1.7.0
-@author Carsten Haitzler <raster\@rasterman.com>
-@author Compuphase http://www.compuphase.com
-@date 2004-2012
+@section toc Table of Contents
 
-@section intro What is Embryo?
+@li @ref embryo_main_intro
+@li @ref embryo_main_compiling
+@li @ref embryo_main_next_steps
+
+@section embryo_main_intro Introduction
 
 Embryo is a tiny library designed to interpret limited Small programs
 compiled by the included compiler, @c embryo_cc.  It is mostly a cleaned
@@ -26,16 +28,40 @@ For more information about the Pawn language, see
 @latexonly http://www.compuphase.com/pawn/pawn.htm @endlatexonly
 For the basics about the Small language, see @ref Small_Page.
 
-@section How_to_Use How to Use Embryo?
+@section embryo_main_compiling How to compile
+
+Embryo is a library your application links to. The procedure for this
+is very simple. You simply have to compile your application with the
+appropriate compiler flags that the @p pkg-config script outputs. For
+example:
+
+Compiling C or C++ files into object files:
+
+@verbatim
+gcc -c -o main.o main.c `pkg-config --cflags embryo`
+@endverbatim
+
+Linking object files into a binary executable:
+
+@verbatim
+gcc -o my_application main.o `pkg-config --libs embryo`
+@endverbatim
+
+See @ref pkgconfig
+
+@section embryo_main_next_steps Next Steps
+
+After you understood what Embryo is and installed it in your system you
+should proceed understanding the programming interface.
+
+Recommended reading:
+
+@li @ref Embryo_Program_Creation_Group to create Embryo from memory or file.
+@li @ref Embryo_Func_Group to expose functions to Embryo.
+@li @ref Embryo_Program_VM_Group to push pop virtual machine.
+@li @ref Embryo_Run_Group to run it.
 
-To use Embryo in your code, you need to do at least the following:
 
-@li Include @ref Embryo.h.
-@li Load the Embryo program using one of the 
-    @ref Embryo_Program_Creation_Group.
-@li Set up the native calls with @ref embryo_program_native_call_add.
-@li Create a virtual machine with @ref embryo_program_vm_push.
-@li Then run the program with @ref embryo_program_run.
 
 @todo Clean up compiler code.
 @todo Proper overview of the operation of the interpreter, that is how

src/lib/eo/Eo.h

@@ -64,11 +64,62 @@ enum _Eo_Op_Type
 typedef enum _Eo_Op_Type Eo_Op_Type;
 
 /**
- * @defgroup Eo Eo Generic Object System
+ * @page eo_main Eo
+ *
+ * @date 2012 (created)
+ *
+ * @section toc Table of Contents
+ *
+ * @li @ref eo_main_intro
+ * @li @ref eo_main_compiling
+ * @li @ref eo_main_next_steps
+ * @li @ref eo_main_intro_example
+ *
+ * @section eo_main_intro Introduction
  *
  * The Eo generic object system. It was designed to be the base object
  * system for the EFL.
+
+ * @section eo_main_compiling How to compile
+ *
+ * Eo is a library your application links to. The procedure for this is
+ * very simple. You simply have to compile your application with the
+ * appropriate compiler flags that the @c pkg-config script outputs. For
+ * example:
+ *
+ * Compiling C or C++ files into object files:
+ *
+ * @verbatim
+   gcc -c -o main.o main.c `pkg-config --cflags eo`
+   @endverbatim
+ *
+ * Linking object files into a binary executable:
+ *
+ * @verbatim
+   gcc -o my_application main.o `pkg-config --libs eo`
+   @endverbatim
+ *
+ * See @ref pkgconfig
+ *
+ * @section eo_main_next_steps Next Steps
+ *
+ * After you understood what Eo is and installed it in your system
+ * you should proceed understanding the programming interface.
+ *
+ * Recommended reading:
+ *
+ * @li @ref Eo_Class_Base
+ * @li @ref Eo_Class
+ * @li @ref Eo_Events
+ * @li @ref Eo_Composite_Objects
+ *
+ * @section eo_main_intro_example Introductory Example
+ *
+ * @ref Eo_Tutorial
+
+ *
  *
+ * @addtogroup Eo
  * @{
  */
 

src/lib/escape/Escape.h

@@ -20,18 +20,51 @@
 
 /**
  * @page escape_main Escape
- * @date 2011
+ * @date 2011 (created)
  *
- * @section intro_sec Introduction
+ * @section toc Table of Contents
+ *
+ * @li @ref escape_main_intro
+ * @li @ref escape_main_compiling
+ * @li @ref escape_main_next_steps
+ *
+ * @section escape_main_intro Introduction
  *
  * The Escape library is a library that acts implements some of the missing
  * function from the PS3 GameOS system that are needed for the proper
  * functioning of the EFL.
  *
- * @section escape_sec Escape API Documentation
+ * @section escape_main_compiling How to compile
+ *
+ * Escape is a library your application links to. The procedure for
+ * this is very simple. You simply have to compile your application
+ * with the appropriate compiler flags that the @p pkg-config script
+ * outputs. For example:
+ *
+ * Compiling C or C++ files into object files:
+ *
+ * @verbatim
+   gcc -c -o main.o main.c `pkg-config --cflags escape`
+   @endverbatim
+ *
+ * Linking object files into a binary executable:
+ *
+ * @verbatim
+   gcc -o my_application main.o `pkg-config --libs escape`
+   @endverbatim
+ *
+ * See @ref pkgconfig
+ *
+ * @section escape_main_next_steps Next Steps
+ *
+ * After you understood what Escape is and installed it in your system
+ * you should proceed understanding the programming interface.
  *
- * Take a look at the documentation of @ref mmap/munmap.
+ * Recommended reading:
  *
+ * @li @ref Escape_Libgen_Group
+ * @li @ref Escape_Unistd_Group
+ * @li @ref Escape_Mman
  */
 
 #include "escape_libgen.h"

src/lib/evas/Evas.h

@@ -1,25 +1,18 @@
 /**
    @page evas_main Evas
 
-   @version 1.7
-   @date 2000-2012
-
-   Please see the @ref authors page for contact details.
-   @link Evas.h Evas API @endlink
-
-   @link Evas.h Evas API @endlink
+   @date 2000 (created)
 
    @section toc Table of Contents
 
    @li @ref evas_main_intro
    @li @ref evas_main_work
    @li @ref evas_main_compiling
-   @li @ref evas_main_install
    @li @ref evas_main_next_steps
    @li @ref evas_main_intro_example
 
 
-   @section evas_main_intro What is Evas?
+   @section evas_main_intro Introduction
 
    Evas is a clean display canvas API for several target display systems
    that can draw anti-aliased text, smooth super and sub-sampled scaled
@@ -46,7 +39,7 @@
 
    Evas is not a widget set or widget toolkit, however it is their
    base. See Elementary (http://docs.enlightenment.org/auto/elementary/)
-   for a toolkit based on Evas, Edje, Ecore and other Enlightenment
+   for a toolkit based on Evas, Edje, @ref Ecore and other Enlightenment
    technologies.
 
    It is not dependent or aware of main loops, input or output
@@ -54,8 +47,8 @@
    Evas. Similarly, it will not create windows or report windows updates
    to your system, rather just drawing the pixels and reporting to the
    user the areas that were changed. Of course these operations are quite
-   common and thus they are ready to use in Ecore, particularly in
-   Ecore_Evas (http://docs.enlightenment.org/auto/ecore/).
+   common and thus they are ready to use in @ref Ecore, particularly in
+   @ref Ecore_Evas_Group.
 
 
    @section evas_main_work How does Evas work?
@@ -184,7 +177,7 @@
    scrollbars, sliders, push buttons etc.
 
 
-   @section evas_main_compiling How to compile using Evas ?
+   @section evas_main_compiling How to compile
 
    Evas is a library your application links to. The procedure for this is
    very simple. You simply have to compile your application with the
@@ -203,42 +196,17 @@
    gcc -o my_application main.o `pkg-config --libs evas`
    @endverbatim
 
-   You simply have to make sure that @c pkg-config is in your shell's @c
-   PATH (see the manual page for your appropriate shell) and @c evas.pc
-   in @c /usr/lib/pkgconfig or its path in the @c PKG_CONFIG_PATH
-   environment variable. It's that simple to link and use Evas once you
-   have written your code to use it.
-
-   Since the program is linked to Evas, it is now able to use any
-   advertised API calls to display graphics in a canvas managed by it, as
-   well as use the API calls provided to manage data.
-
-   You should make sure you add any extra compile and link flags to your
-   compile commands that your application may need as well. The above
-   example is only guaranteed to make Evas add it's own requirements.
-
-
-   @section evas_main_install How is it installed?
-
-   Simple:
-
-   @verbatim
-   ./configure
-   make
-   su -
-   ...
-   make install
-   @endverbatim
+   See @ref pkgconfig
 
    @section evas_main_next_steps Next Steps
 
-   After you understood what Evas is and installed it in your system you
-   should proceed understanding the programming interface for all
+   After you understood what Evas is and installed it in your system
+   you should proceed understanding the programming interface for all
    objects, then see the specific for the most used elements. We'd
-   recommend you to take a while to learn Ecore
-   (http://docs.enlightenment.org/auto/ecore/) and Edje
-   (http://docs.enlightenment.org/auto/edje/) as they will likely save
-   you tons of work compared to using just Evas directly.
+   recommend you to take a while to learn @ref Ecore, Edje
+   (http://docs.enlightenment.org/auto/edje/) and Elementary
+   (http://docs.enlightenment.org/auto/elementary/) as they will
+   likely save you tons of work compared to using just Evas directly.
 
    Recommended reading:
 
@@ -268,6 +236,9 @@
    @section evas_main_intro_example Introductory Example
 
    @include evas-buffer-simple.c
+
+   More examples can be found at @ref evas_examples.
+
  */
 
 #ifndef _EVAS_H

src/lib/evil/Evil.h

@@ -9,10 +9,16 @@
 /**
  * @page evil_main Evil
  * @author Vincent Torri
- * @version 1.7.0
- * @date 2008-2012
+ * @date 2008 (created)
  *
- * @section intro_sec Introduction
+ * @section toc Table of Contents
+ *
+ * @li @ref evil_main_intro
+ * @li @ref evil_main_ack
+ * @li @ref evil_main_compiling
+ * @li @ref evil_main_next_steps
+ *
+ * @section evil_main_intro Introduction
  *
  * The Evil library is an evil library that ports some evil Unix
  * functions to the Windows (XP or above, or Mobile) platform. The
@@ -28,7 +34,7 @@
  * cygwin. To compare the size of the DLL themselves, Evil is around
  * 33 KB and cygwin DLL is around 800 KB.
  *
- * @section acknowledgments_sec Acknowledgments
+ * @section evil_main_ack Acknowledgments
  *
  * This library has receive some from people interested in the EFL or
  * not. Among them, evil thanks to Lars Munch, Raoul Hecky, Nicolas
@@ -36,15 +42,46 @@
  * Vixie, Daniel Stenberg, who helped the author of the library in
  * different fields (code and tests).
  *
- * @section license_sec license
+ * @section evil_main_compiling How to compile
+ *
+ * Evil is a library your application links to. The procedure for
+ * this is very simple. You simply have to compile your application
+ * with the appropriate compiler flags that the @p pkg-config script
+ * outputs. For example:
+ *
+ * Compiling C or C++ files into object files:
+ *
+ * @verbatim
+   gcc -c -o main.o main.c `pkg-config --cflags evil`
+   @endverbatim
+ *
+ * Linking object files into a binary executable:
+ *
+ * @verbatim
+   gcc -o my_application main.o `pkg-config --libs evil`
+   @endverbatim
+ *
+ * See @ref pkgconfig
+ *
+ * @section evil_main_next_steps Next Steps
  *
- * The Evil library is distributes under a modified BSD license. See
- * the files COPYING and COPYING-PLAIN in the top level directory for
- * the full license text.
+ * After you understood what Evil is and installed it in your system
+ * you should proceed understanding the programming interface.
  *
- * @section reference_sec Reference API
+ * Recommended reading:
  *
- * Use the horizontal menu above to navigate into the reference API
+ * @li @ref Evil_Mman
+ * @li @ref Evil_Libgen_Group
+ * @li @ref Evil_Unistd_Group
+ * @li @ref Evil_Dlfcn
+ * @li @ref Evil_Pwd_Group
+ * @li @ref Evil_Stdio_Group
+ * @li @ref Evil_Main_Group
+ * @li @ref Evil_Inet_Group
+ * @li @ref Evil_Dirent_Group
+ * @li @ref Evil_String_Group
+ * @li @ref Evil_Stdlib_Group
+ * @li @ref Evil_Time_Group
  */
 
 /**