efl: Adding *.dox files from various libs.

SVN revision: 81274

doc/Doxyfile.in

@@ -592,7 +592,12 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = @top_srcdir@/src/lib @srcdir@/main.dox
+INPUT                  = @top_srcdir@/src/lib \
+                         @srcdir@/main.dox \
+                         @srcdir@/ecore_examples.dox \
+                         @srcdir@/eet_examples.dox \
+                         @srcdir@/evas_examples.dox \
+                         @builddir@/eio.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

doc/eet_examples.dox

@@ -0,0 +1,184 @@
+/**
+ * @page Examples Examples
+ *
+ * Here is a page with examples.
+ *
+ * @ref Example_Eet_Data_Simple
+ *
+ * @ref Example_Eet_Data_Nested
+ *
+ * @ref Example_Eet_Data_File_Descriptor_01
+ *
+ * @ref Example_Eet_Data_File_Descriptor_02
+ *
+ * @ref Example_Eet_Data_Cipher_Decipher
+ *
+ * <a href="examples.html">List of examples</a>
+ */
+
+/**
+ * @page Example_Eet_Basic Very basic Eet example
+ *
+ * @includelineno eet-basic.c
+ * @example eet-basic.c
+ */
+
+/**
+ * @page Example_Eet_File Example of the various ways to interface with an Eet File
+ *
+ * @includelineno eet-file.c
+ * @example eet-file.c
+ */
+
+/**
+ * @page Example_Eet_Data_Simple Simple data example
+ *
+ * @includelineno eet-data-simple.c
+ * @example eet-data-simple.c
+ */
+
+/**
+ * @page Example_Eet_Data_Nested Nested data example
+ *
+ * @includelineno eet-data-nested.c
+ * @example eet-data-nested.c
+ */
+
+/**
+ * @page Example_Eet_Data_File_Descriptor_01 File descriptor data example
+ *
+ * @includelineno eet-data-file_descriptor_01.c
+ * @example eet-data-file_descriptor_01.c
+ */
+
+/**
+ * @page Example_Eet_Data_File_Descriptor_02 File descriptor data example, with Eet unions and variants
+ *
+ * This is an example much like the one shown in @ref
+ * eet_data_file_descriptor. The difference is that here we're
+ * attaining ourselves to two new data types to store in an Eet file
+ * -- @b unions and @b variants. We don't try to come with data
+ * mapping to real world use cases, here. Instead, we're defining
+ * 3 different simple structures to be used throughout the example:
+ * @dontinclude eet-data-file_descriptor_02.c
+ * @skip typedef struct _Example_Struct1
+ * @until typedef struct _Example_Struct3
+ * @skip struct _Example_Struct1
+ * @until int body
+ * @until };
+ *
+ * To identify, for both union and variant data cases, the type of
+ * each chunk of data, we're defining types to point to each of those
+ * structs:
+ * @dontinclude eet-data-file_descriptor_02.c
+ * @skip typedef enum _Example_Data_Type
+ * @until ;
+ * @skip enum _Example_Data_Type
+ * @until };
+ *
+ * We have also a mapping from those types to name strings, to be used
+ * in the Eet unions and variants @c type_get() and @c type_set() type
+ * identifying callbacks:
+ * @skip struct
+ * @until };
+ *
+ * In this example, we have no fancy hash to store our data into
+ * profiles/accounts, but just two lists for union and variant data
+ * nodes:
+ * @dontinclude eet-data-file_descriptor_02.c
+ * @skip typedef struct _Example_Lists
+ * @until typedef struct _Example_Lists
+ * @skip struct _Example_Lists
+ * @until };
+ *
+ * Let's begin with our unions, then, which look like:
+ * @dontinclude eet-data-file_descriptor_02.c
+ * @skip typedef struct _Example_Union
+ * @until typedef struct _Example_Union
+ * @skip struct _Example_Union
+ * @until };
+ *
+ * The first interesting part of the code is where we define our data
+ * descriptors for the main lists, the unions and all of structures
+ * upon which those two depend.
+ * @dontinclude eet-data-file_descriptor_02.c
+ * @skip declaring types
+ * @until _union_descriptor);
+ * The code for descriptors on @c Example_Struct1, @c Example_Struct2
+ * and @c Example_Struct3 is straightforward, a matter already covered
+ * on @ref eet_data_file_descriptor. What is new, here, are the two
+ * type matching functions for our unions. There, we must set the @c
+ * data pointer to its matching type, on @c _union_type_set and return
+ * the correct matching type, on @c _union_type_get:
+ * @dontinclude eet-data-file_descriptor_02.c
+ * @skip union type_get()
+ * @until _union_type_set
+ * @until _union_type_set
+ *
+ * With the #EET_DATA_DESCRIPTOR_ADD_MAPPING calls, which follow, we
+ * make the the link between our type names and their respective
+ * structs. The code handling actual data is pretty much the same as in
+ * @ref eet_data_file_descriptor -- one uses command line arguments to
+ * enter new data chunks (or just to visualize the contents of an Eet
+ * file), signalling if they are unions or variants. One must also
+ * pass the type of the data chuck to enter, with integers 1, 2 or
+ * 3. Then, come the fields for each type:
+ * @dontinclude eet-data-file_descriptor_02.c
+ * @skip Usage
+ * @until argv
+ *
+ * Variants are very similar to unions, except that data chunks need
+ * @b not contain previously allocated space for each of the possible
+ * types of data going in them:
+ * @dontinclude eet-data-file_descriptor_02.c
+ * @skip typedef struct _Example_Variant
+ * @until typedef struct _Example_Variant
+ * @skip struct _Example_Variant_Type
+ * @until };
+ * @until };
+ *
+ * The code declaring the data descriptors and handling the data is
+ * very similar to the unions part, and is left for the reader to
+ * check for him/herself. The complete code of the example follows.
+ *
+ * @includelineno eet-data-file_descriptor_02.c
+ * @example eet-data-file_descriptor_02.c
+ */
+
+/**
+ * @page Example_Eet_Data_Cipher_Decipher Eet data cipher/decipher example
+ *
+ * In this example, we exemplify the usage of eet_write_cipher() and
+ * eet_read_cipher(). For it to work, <b>make sure</b> to have your
+ * Eet installation with a ciphering backend enabled.
+ *
+ * We start by defining the information to record in an Eet file (@c
+ * buffer), the key to cipher that (@c key) and a dummy wrong key to
+ * try to access that information, later (@c key_bad).
+ * @dontinclude eet-data-cipher_decipher.c
+ * @skip buffer =
+ * @until bad =
+ *
+ * After opening our file, we simply use the first cited function to
+ * write our string ciphered:
+ * @dontinclude eet-data-cipher_decipher.c
+ * @skip eet_open
+ * @until eet_close
+ *
+ * Then, after closing it on purpose, we open it again, to retrieve
+ * the encrypted information back, in a readable format:
+ * @skip eet_open
+ * @until eet_close
+ * @until eet_close
+ *
+ * Note that we do it twice, being the last time with the wrong
+ * key. In this last case, if the information is read back and matches
+ * the original @c buffer, something wrong is going on (we made it to
+ * fail on purpose). The former access is OK, and must work.
+ *
+ * What we do in sequence is just to delete the file. The complete
+ * code of the example follows.
+ *
+ * @includelineno eet-data-cipher_decipher.c
+ * @example eet-data-cipher_decipher.c
+ */

doc/eio.dox.in

@@ -0,0 +1,456 @@
+/* EIO - EFL data type library
+ * Copyright (C) 2010 Enlightenment Developers:
+ *           Cedric Bail <cedric.bail@free.fr>
+ *           Vincent "caro" Torri  <vtorri at univ-evry dot fr>
+ *	     Stephen "okra" Houston <unixtitan@gmail.com>
+ *           Gustavo Sverzut Barbieri <barbieri@gmail.com>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library;
+ * if not, see <http://www.gnu.org/licenses/>.
+ */
+
+/**
+ * @page eio_main Eio
+ * @author Cedric Bail <cedric.bail@@free.fr>
+ * @author Stephen "okra" Houston <unixtitan@@gmail.com>
+ * @author Gustavo Sverzut Barbieri <barbieri@@gmail.com>
+ * @author Vincent "caro" Torri  <vtorri at univ-evry dot fr>
+ * @author Guillaume "kuri" Friloux <guillaume.friloux@@asp64.com>
+ * @date 2010-2012
+ *
+ * @section eio_intro_sec Introduction
+ * @version @PACKAGE_VERSION@
+ *
+ * The Eio library is a library that implements an API for asynchronous
+ * input/output operation. Most operation are done in a separated thread
+ * to prevent lock. See @ref Eio_Group. Some helper to work on data
+ * received in Eio callback are also provided see @ref Eio_Helper.
+ * It is also possible to work asynchronously on Eina_File with @ref Eio_Map
+ * or on Eet_File with @ref Eio_Eet. It come with way to manipulate
+ * eXtended attribute assynchronously with @ref Eio_Xattr.
+ *
+ * This library is cross-platform and can be compiled and used on
+ * Linux, BSD, Opensolaris and Windows (XP and CE).
+ */
+
+/**
+ * @page tutorial_dir_copy eio_dir_copy() tutorial
+ *
+ * To use eio_dir_copy(), you basically need the source and
+ * destination files (or directories), and set three callbacks:
+ *
+ * @li The notification callback, which allows you to know if a file or
+ * a directory is copied, and the progress of the copy.
+ * @li The end callback, which is called when the copy is finished.
+ * @li The error callback, which is called if an error occured. You
+ * can then retrieve the error type as an errno error.
+ *
+ * @warning It is the user's duty to provide the "right target". It
+ * means that copying to '.' will copy the content directly inside '.'
+ * and not in a subdirectory.
+ *
+ * Here is a simple example:
+ *
+ * @code
+ * #include <Ecore.h>
+ * #include <Eio.h>
+ *
+ * static void
+ * _test_notify_cb(void *data, Eio_File *handler, const Eio_Progress *info)
+ * {
+ *    switch (info->op)
+ *       {
+ *       case EIO_FILE_COPY:
+ *          printf("[%s] %f%%\n", info->dest, info->percent);
+ *          break;
+ *       case EIO_DIR_COPY:
+ *          printf("global [%li/%li] %f%%\n", info->current, info->max, info->percent);
+ *          break;
+ *       }
+ * }
+ *
+ * static void
+ * _test_done_cb(void *data, Eio_File *handler)
+ * {
+ *    printf("copy done\n");
+ *    ecore_main_loop_quit();
+ * }
+ *
+ * static void
+ * _test_error_cb(int error, Eio_File *handler, void *data)
+ * {
+ *    fprintf(stderr, "error: [%s]\n", strerror(error));
+ *     ecore_main_loop_quit();
+ * }
+ *
+ * int
+ * main(int argc, char **argv)
+ * {
+ *    Eio_File *cp;
+ *
+ *    if (argc != 3)
+ *      {
+ *         fprintf(stderr, "eio_cp source_file destination_file\n");
+ *         return -1;
+ *      }
+ *
+ *    ecore_init();
+ *    eio_init();
+ *
+ *    cp = eio_dir_copy(argv[1], argv[2],
+ *                      _test_notify_cb,
+ *                      _test_done_cb,
+ *                      _test_error_cb,
+ *                      NULL);
+ *
+ *    ecore_main_loop_begin();
+ *
+ *    eio_shutdown();
+ *    ecore_shutdown();
+ *
+ *    return 0;
+ * }
+ * @endcode
+ */
+
+/**
+ * @page tutorial_dir_stat_ls eio_dir_stat_ls() tutorial
+ *
+ * @li The filter callback, which allow or not a file to be seen
+ * by the main loop handler. This callback run in a separated thread.
+ * @li The main callback, which receive in the main loop all the file
+ * that are allowed by the filter. If you are updating a user interface
+ * it make sense to delay the insertion a little, so you get a chance
+ * to update the canvas for a bunch of file instead of one by one.
+ * @li The end callback, which is called in the main loop when the
+ * content of the directory has been correctly scanned and all the
+ * file notified to the main loop.
+ * @li The error callback, which is called if an error occured or
+ * if the listing was cancelled during it's run. You can then retrieve
+ * the error type as an errno error.
+ *
+ * Here is a simple example that implement a stupidly simple replacement for find:
+ *
+ * @code
+ * #include <Ecore.h>
+ * #include <Eio.h>
+ *
+ * static Eina_Bool
+ * _test_filter_cb(void *data, Eio_File *handler, const Eina_File_Direct_Info *info)
+ * {
+ *    fprintf(stderr, "ACCEPTING: %s\n", info->path);
+ *    return EINA_TRUE;
+ * }
+ *
+ * static void
+ * _test_main_cb(void *data, Eio_File *handler, const Eina_File_Direct_Info *info)
+ * {
+ *    fprintf(stderr, "PROCESS: %s\n", info->path);
+ * }
+ *
+ * static void
+ * _test_done_cb(void *data, Eio_File *handler)
+ * {
+ *    printf("ls done\n");
+ *    ecore_main_loop_quit();
+ * }
+ *
+ * static void
+ * _test_error_cb(void *data, Eio_File *handler, int error)
+ * {
+ *    fprintf(stderr, "error: [%s]\n", strerror(error));
+ *    ecore_main_loop_quit();
+ * }
+ *
+ * int
+ * main(int argc, char **argv)
+ * {
+ *    Eio_File *cp;
+ *
+ *    if (argc != 2)
+ *      {
+ * 	fprintf(stderr, "eio_ls directory\n");
+ * 	return -1;
+ *      }
+ *
+ *    ecore_init();
+ *    eio_init();
+ *
+ *    cp = eio_dir_stat_ls(argv[1],
+ *                         _test_filter_cb,
+ *                         _test_main_cb,
+ *                         _test_done_cb,
+ *                         _test_error_cb,
+ *                         NULL);
+ *
+ *    ecore_main_loop_begin();
+ *
+ *    eio_shutdown();
+ *    ecore_shutdown();
+ *
+ *    return 0;
+ * }
+ *
+ * @endcode
+ */
+
+/**
+ * @page tutorial_file_ls eio_file_ls() tutorial
+ *
+ * To use eio_file_ls(), you just need to define four callbacks:
+ *
+ * @li The filter callback, which allow or not a file to be seen
+ * by the main loop handler. This callback run in a separated thread.
+ * @li The main callback, which receive in the main loop all the file
+ * that are allowed by the filter. If you are updating a user interface
+ * it make sense to delay the insertion a little, so you get a chance
+ * to update the canvas for a bunch of file instead of one by one.
+ * @li The end callback, which is called in the main loop when the
+ * content of the directory has been correctly scanned and all the
+ * file notified to the main loop.
+ * @li The error callback, which is called if an error occured or
+ * if the listing was cancelled during it's run. You can then retrieve
+ * the error type as an errno error.
+ *
+ * Here is a simple example:
+ *
+ * @code
+ * #include <Ecore.h>
+ * #include <Eio.h>
+ *
+ * static Eina_Bool
+ * _test_filter_cb(void *data, Eio_File *handler, const char *file)
+ * {
+ *    fprintf(stderr, "ACCEPTING: %s\n", file);
+ *    return EINA_TRUE;
+ * }
+ *
+ * static void
+ * _test_main_cb(void *data, Eio_File *handler, const char *file)
+ * {
+ *    fprintf(stderr, "PROCESS: %s\n", file);
+ * }
+ *
+ * static void
+ * _test_done_cb(void *data, Eio_File *handler)
+ * {
+ *    printf("ls done\n");
+ *    ecore_main_loop_quit();
+ * }
+ *
+ * static void
+ * _test_error_cb(void *data, Eio_File *handler, int error)
+ * {
+ *    fprintf(stderr, "error: [%s]\n", strerror(error));
+ *    ecore_main_loop_quit();
+ * }
+ *
+ * int
+ * main(int argc, char **argv)
+ * {
+ *    Eio_File *cp;
+ *
+ *    if (argc != 2)
+ *      {
+ * 	fprintf(stderr, "eio_ls directory\n");
+ * 	return -1;
+ *      }
+ *
+ *    ecore_init();
+ *    eio_init();
+ *
+ *    cp = eio_file_ls(argv[1],
+ *                     _test_filter_cb,
+ *                     _test_main_cb,
+ *                     _test_done_cb,
+ *                     _test_error_cb,
+ *                     NULL);
+ *
+ *    ecore_main_loop_begin();
+ *
+ *    eio_shutdown();
+ *    ecore_shutdown();
+ *
+ *    return 0;
+ * }
+ *
+ * @endcode
+ */
+
+/**
+ * @page tutorial_monitor_add eio_monitor_add() tutorial
+ *
+ * To use eio_monitor_add(), you have to define callbacks
+ * for events declared by eio.
+ * Available events are :
+ * - EIO_MONITOR_FILE_CREATED
+ * - EIO_MONITOR_FILE_DELETED
+ * - EIO_MONITOR_FILE_MODIFIED
+ * - EIO_MONITOR_FILE_CLOSED
+ * - EIO_MONITOR_DIRECTORY_CREATED
+ * - EIO_MONITOR_DIRECTORY_DELETED
+ * - EIO_MONITOR_DIRECTORY_CLOSED
+ * - EIO_MONITOR_SELF_RENAME
+ * - EIO_MONITOR_SELF_DELETED
+ *
+ * As nothing is worth an example, here it is :
+ * @code
+ * #include <Eina.h>
+ * #include <Ecore.h>
+ * #include <Eio.h>
+ *
+ * void file_modified(void *data, int type, void *event)
+ * {
+ *    const char *filename = (const char *)data;
+ *    printf("file %s ", filename);
+ *    if( type == EIO_MONITOR_FILE_MODIFIED )
+ *       printf("is being modified");
+ *    else if( type == EIO_MONITOR_FILE_CLOSED )
+ *       printf("is not more being modified");
+ *    else printf("got unexpected changes");
+ *    printf("\n");
+ * }
+ *
+ * int main(int argc, char **argv) {
+ *    Eio_Monitor *monitor  = NULL,
+ *                *monitor2 = NULL;
+ *    eio_init();
+ *    const char *filename = eina_stringshare_add("/tmp/eio_notify_testfile");
+ *
+ *    monitor  = eio_monitor_add(filename);
+ *    ecore_event_handler_add(EIO_MONITOR_FILE_MODIFIED, (Ecore_Event_Handler_Cb)file_modified, filename);
+ *    ecore_event_handler_add(EIO_MONITOR_FILE_CLOSED, (Ecore_Event_Handler_Cb)file_modified, filename);
+ *
+ *    ecore_main_loop_begin();
+ *    eio_shutdown();
+ *    eina_stringshare_del(filename);
+ * }
+ * @endcode
+ * Build the example doing :
+ * @verbatim gcc -o tutorial_monitor_add tutorial_monitor_add.c `pkg-config --libs --cflags eio ecore ecore-file eina`
+ * then create the file /tmp/eio_notify_testfile :
+ * touch /tmp/eio_notify_testfile
+ * and launch tutorial_monitor_add, and in another terminal, write into /tmp/eio_notify_testfile, doing for example :
+ * echo "test" >> /tmp/eio_notify_testfile
+ * @endverbatim
+ */
+
+/**
+ * @page tutorial_dir_direct_ls eio_dir_direct_ls() tutorial
+ *
+ * @li The filter callback, which allow or not a file to be seen
+ * by the main loop handler. This callback run in a separated thread.
+ * It also take care of getting a stat buffer needed by the main callback
+ * to display the file size.
+ * @li The main callback, which receive in the main loop all the file
+ * that are allowed by the filter. If you are updating a user interface
+ * it make sense to delay the insertion a little, so you get a chance
+ * to update the canvas for a bunch of file instead of one by one.
+ * @li The end callback, which is called in the main loop when the
+ * content of the directory has been correctly scanned and all the
+ * file notified to the main loop.
+ * @li The error callback, which is called if an error occured or
+ * if the listing was cancelled during it's run. You can then retrieve
+ * the error type as an errno error.
+ *
+ * Here is a simple example that implement a stupidly simple recursive ls that display file size:
+ *
+ * @code
+ * #include <Eina.h>
+ * #include <Ecore.h>
+ * #include <Eio.h>
+ *
+ * static Eina_Bool
+ * _test_filter_cb(void *data, Eio_File *handler, Eina_File_Direct_Info *info)
+ * {
+ *    Eina_Stat *buffer;
+ *    Eina_Bool isdir;
+ *
+ *    isdir = info->type == EINA_FILE_DIR;
+ *
+ *    buffer = malloc(sizeof (Eina_Stat));
+ *    if (eina_file_statat(eio_file_container_get(handler), info, buffer))
+ *      {
+ *         free(buffer);
+ *         return EINA_FALSE;
+ *      }
+ *
+ *    if (!isdir && info->type == EINA_FILE_DIR)
+ *      {
+ *         struct stat st;
+ *         if (lstat(info->path, &st) == 0)
+ *           {
+ *              if (S_ISLNK(st.st_mode))
+ *                info->type = EINA_FILE_LNK;
+ *           }
+ *      }
+ *
+ *    eio_file_associate_direct_add(handler, "stat", buffer, free);
+ *    fprintf(stdout, "ACCEPTING: %s\n", info->path);
+ *    return EINA_TRUE;
+ * }
+ *
+ * static void
+ * _test_main_cb(void *data, Eio_File *handler, const Eina_File_Direct_Info *info)
+ * {
+ *    struct stat *buffer;
+ *
+ *    buffer = eio_file_associate_find(handler, "stat");
+ *    fprintf(stdout, "PROCESS: %s of size %li\n", info->path, buffer->st_size);
+ * }
+ *
+ * static void
+ * _test_done_cb(void *data, Eio_File *handler)
+ * {
+ *    printf("ls done\n");
+ *    ecore_main_loop_quit();
+ * }
+ *
+ * static void
+ * _test_error_cb(void *data, Eio_File *handler, int error)
+ * {
+ *    fprintf(stdout, "error: [%s]\n", strerror(error));
+ *    ecore_main_loop_quit();
+ * }
+ *
+ * int
+ * main(int argc, char **argv)
+ * {
+ *    Eio_File *cp;
+ *
+ *    if (argc != 2)
+ *      {
+ * 	fprintf(stdout, "eio_ls directory\n");
+ * 	return -1;
+ *      }
+ *
+ *    ecore_init();
+ *    eio_init();
+ *
+ *    cp = eio_dir_direct_ls(argv[1],
+ * 			  _test_filter_cb,
+ * 			  _test_main_cb,
+ * 			  _test_done_cb,
+ * 			  _test_error_cb,
+ * 			  NULL);
+ *
+ *    ecore_main_loop_begin();
+ *
+ *    eio_shutdown();
+ *    ecore_shutdown();
+ *
+ *    return 0;
+ * }
+ * @endcode
+ */