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

8 files changed, 274 insertions, 53 deletions

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index 2c00f2d4f..c93922a0c 100644
--- a/doc/Doxyfile.in
+++ b/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
diff --git a/doc/edbus_examples.dox b/doc/edbus_examples.dox
new file mode 100644
index 000000000..08c687d67
--- /dev/null
+++ b/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.
+ */
diff --git a/doc/eet_examples.dox b/doc/eet_examples.dox
index 20c19c389..20c117782 100644
--- a/doc/eet_examples.dox
+++ b/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>
  */
 
 /**
diff --git a/doc/eina_examples.dox b/doc/eina_examples.dox
new file mode 100644
index 000000000..95f64fd40
--- /dev/null
+++ b/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
+ */
diff --git a/doc/eo_tutorial.dox b/doc/eo_tutorial.dox
index c30da62e4..364ff5415 100644
--- a/doc/eo_tutorial.dox
+++ b/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
diff --git a/doc/head.html b/doc/head.html
index 9227da5ee..e09929160 100644
--- a/doc/head.html
+++ b/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>
diff --git a/doc/main.dox b/doc/main.dox
index 950f80563..0b10bae8e 100644
--- a/doc/main.dox
+++ b/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.
  *
  */
 
@@ -118,55 +119,61 @@
  */
 
 /**
+ * @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).
  */
diff --git a/doc/pkgconfig.dox b/doc/pkgconfig.dox
new file mode 100644
index 000000000..fbd3baeb6
--- /dev/null
+++ b/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
+
+*/