From 5a8f45a560bbab811e0edd223d53c9c66732f33b Mon Sep 17 00:00:00 2001 From: "Jonas M. Gastal" Date: Fri, 15 Jun 2012 19:08:03 +0000 Subject: [PATCH] Improving Eio Doc and adding an example. Author: Guilherme Iscaro SVN revision: 72202 --- legacy/eio/configure.ac | 5 + legacy/eio/m4/efl_examples.m4 | 63 ++++++++++ legacy/eio/src/Makefile.am | 3 +- legacy/eio/src/examples/Makefile.am | 29 +++++ legacy/eio/src/examples/eio_file_ls.c | 74 ++++++++++++ legacy/eio/src/lib/Eio.h | 161 +++++++++++++++++--------- 6 files changed, 277 insertions(+), 58 deletions(-) create mode 100644 legacy/eio/m4/efl_examples.m4 create mode 100644 legacy/eio/src/examples/Makefile.am create mode 100644 legacy/eio/src/examples/eio_file_ls.c diff --git a/legacy/eio/configure.ac b/legacy/eio/configure.ac index 545928ec80..2d48523d38 100644 --- a/legacy/eio/configure.ac +++ b/legacy/eio/configure.ac @@ -257,6 +257,8 @@ EIO_CHECK_NOTIFY_WIN32([${want_notify_win32}], [have_notify_win32="yes"], [have_ AM_CONDITIONAL([EIO_HAVE_INOTIFY], [test "x$have_inotify" = "xyes"]) AM_CONDITIONAL([EIO_HAVE_WINCHANGE], [test "x$have_notify_win32" = "xyes"]) +EFL_CHECK_BUILD_EXAMPLES([enable_build_examples="yes"], [enable_build_examples="no"]) +EFL_CHECK_INSTALL_EXAMPLES([enable_install_examples="yes"], [enable_install_examples="no"]) AC_OUTPUT([ @@ -268,6 +270,7 @@ doc/eio.dox doc/Doxyfile src/Makefile src/lib/Makefile +src/examples/Makefile ]) echo @@ -285,6 +288,8 @@ echo " Inotify..............: ${have_inotify}" echo " Windows notification.: ${have_notify_win32}" echo echo " Documentation........: ${build_doc}" +echo " Examples...............: ${enable_build_examples}" +echo " Examples installed.....: ${enable_install_examples}" echo echo "Compilation............: make (or gmake)" echo " CPPFLAGS.............: $CPPFLAGS" diff --git a/legacy/eio/m4/efl_examples.m4 b/legacy/eio/m4/efl_examples.m4 new file mode 100644 index 0000000000..2a809adff5 --- /dev/null +++ b/legacy/eio/m4/efl_examples.m4 @@ -0,0 +1,63 @@ +dnl Copyright (C) 2008 Vincent Torri +dnl That code is public domain and can be freely used or copied. + +dnl Macro that check if building examples is wanted. + +dnl Usage: EFL_CHECK_BUILD_EXAMPLES([ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]) +dnl Defines the automake conditionnal EFL_ENABLE_BUILD_EXAMPLES + +AC_DEFUN([EFL_CHECK_BUILD_EXAMPLES], +[ + +dnl configure option + +AC_ARG_ENABLE([build-examples], + [AC_HELP_STRING([--enable-build-examples], [enable building examples @<:@default=disabled@:>@])], + [ + if test "x${enableval}" = "xyes" ; then + _efl_enable_build_examples="yes" + else + _efl_enable_build_examples="no" + fi + ], + [_efl_enable_build_examples="no"]) + +AC_MSG_CHECKING([whether examples are built]) +AC_MSG_RESULT([${_efl_enable_build_examples}]) + +AM_CONDITIONAL(EFL_BUILD_EXAMPLES, test "x${_efl_enable_build_examples}" = "xyes") + +AS_IF([test "x$_efl_enable_build_examples" = "xyes"], [$1], [$2]) +]) + + +dnl Macro that check if installing examples is wanted. + +dnl Usage: EFL_CHECK_INSTALL_EXAMPLES([ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]) +dnl Defines the automake conditionnal EFL_ENABLE_INSTALL_EXAMPLES + +AC_DEFUN([EFL_CHECK_INSTALL_EXAMPLES], +[ + +dnl configure option + +AC_ARG_ENABLE([install-examples], + [AC_HELP_STRING([--enable-install-examples], [enable installing example source files @<:@default=disabled@:>@])], + [ + if test "x${enableval}" = "xyes" ; then + _efl_enable_install_examples="yes" + else + _efl_enable_install_examples="no" + fi + ], + [_efl_enable_install_examples="no"]) + +AC_MSG_CHECKING([whether examples are installed]) +AC_MSG_RESULT([${_efl_enable_install_examples}]) + +AM_CONDITIONAL(EFL_INSTALL_EXAMPLES, test "x${_efl_enable_install_examples}" = "xyes") + +AS_IF([test "x$_efl_enable_install_examples" = "xyes"], [$1], [$2]) +]) + +dnl End of efl_examples.m4 diff --git a/legacy/eio/src/Makefile.am b/legacy/eio/src/Makefile.am index 2433e6cc47..34a2f0ed3b 100644 --- a/legacy/eio/src/Makefile.am +++ b/legacy/eio/src/Makefile.am @@ -1,3 +1,4 @@ MAINTAINERCLEANFILES = Makefile.in -SUBDIRS = lib +SUBDIRS = lib \ + examples diff --git a/legacy/eio/src/examples/Makefile.am b/legacy/eio/src/examples/Makefile.am new file mode 100644 index 0000000000..53dfeb2dd6 --- /dev/null +++ b/legacy/eio/src/examples/Makefile.am @@ -0,0 +1,29 @@ +MAINTAINERCLEANFILES = Makefile.in + +examplesdir = $(datadir)/$(PACKAGE)/examples + +filesdir = $(datadir)/$(PACKAGE)/examples +files_DATA = + +AM_CPPFLAGS = \ +-I. \ +-I$(top_srcdir)/src/lib/ \ +@EIO_CFLAGS@ @EFL_EIO_BUILD@ + +ECOREBASELDADD = \ + $(top_builddir)/src/lib/libeio.la + + +LDADD = \ + $(ECOREBASELDADD) + +SRCS = \ + eio_file_ls.c + +examples_PROGRAMS = + +if EFL_BUILD_EXAMPLES +examples_PROGRAMS += \ + eio_file_ls + +endif diff --git a/legacy/eio/src/examples/eio_file_ls.c b/legacy/eio/src/examples/eio_file_ls.c new file mode 100644 index 0000000000..7a9e7f548b --- /dev/null +++ b/legacy/eio/src/examples/eio_file_ls.c @@ -0,0 +1,74 @@ +/** + * Compile with gcc -o eio_file_ls eio_file_ls.c `pkg-config --cflags --libs ecore eio` + */ + +#include +#include +#include +#include +#include + +static Eina_Bool +_filter_cb(void *data, Eio_File *handler, const char *file) +{ + char *last_slash = strrchr(file, '/'); + + //Check if it is a hidden file + if (last_slash != NULL && strlen(last_slash) > 1 && last_slash[1] == '.') + return EINA_FALSE; + + return EINA_TRUE; +} + +static void +_main_cb(void *data, Eio_File *handler, const char *file) +{ + int *number_of_listed_files = (int *)data; + + fprintf(stdout, "Processing file:%s\n", file); + + (*number_of_listed_files)++; +} + +static void +_done_cb(void *data, Eio_File *handler) +{ + int *number_of_listed_files = (int *)data; + + fprintf(stdout, "Number of listed files:%d\n" \ + "ls operation is done, quitting.\n", *number_of_listed_files); + + ecore_main_loop_quit(); +} + +static void +_error_cb(void *data, Eio_File *handler, int error) +{ + fprintf(stderr, "Something wrong has happend:%s\n", strerror(error)); + ecore_main_loop_quit(); +} + +int +main(int argc, char **argv) +{ + int number_of_listed_files = 0; + + ecore_init(); + eio_init(); + + if (argc < 2) + { + fprintf(stderr, "You must pass a path to execute the command.\n"); + return -1; + } + + eio_file_ls(argv[1], _filter_cb, _main_cb, _done_cb, _error_cb, + &number_of_listed_files); + + ecore_main_loop_begin(); + + eio_shutdown(); + ecore_shutdown(); + + return 0; +} diff --git a/legacy/eio/src/lib/Eio.h b/legacy/eio/src/lib/Eio.h index 213bfcad17..405375175e 100644 --- a/legacy/eio/src/lib/Eio.h +++ b/legacy/eio/src/lib/Eio.h @@ -63,12 +63,16 @@ extern "C" { #define EIO_VERSION_MAJOR 1 #define EIO_VERSION_MINOR 0 + /** + * @typedef Eio_Version + * Represents the current version of EIO + */ typedef struct _Eio_Version { - int major; - int minor; - int micro; - int revision; + int major; /**< Major version number */ + int minor; /**< Minor version number */ + int micro; /**< Micro version number */ + int revision; /**< Revision number */ } Eio_Version; EAPI extern Eio_Version *eio_version; @@ -80,14 +84,20 @@ extern "C" { * * All the functions in this group perform input/output operations * in a separate thread using the infrastructure provided by - * Ecore_Thread and Eina. + * Ecore_Thread and Eina, this means that all functions here are non-blocking. + * + * The functions displayed here are used to make basic file operations, like + * listing the content of a directory, creating a new directory, etc. * * @{ */ /** * @enum _Eio_File_Op - * Input/Output operations on files. + * + * @brief Input/Output operations on files. + * + * This enum represents the operations that can be done. */ enum _Eio_File_Op { @@ -148,6 +158,10 @@ typedef void (*Eio_Done_Cb)(void *data, Eio_File *handler); typedef void (*Eio_Error_Cb)(void *data, Eio_File *handler, int error); typedef void (*Eio_Eet_Error_Cb)(void *data, Eio_File *handler, Eet_Error err); +/** + * @struct _Eio_Progress + * @brief Represents the current progress of the operation. + */ struct _Eio_Progress { Eio_File_Op op; /**< I/O type */ @@ -163,15 +177,18 @@ struct _Eio_Progress /** * @brief List contents of a directory without locking your app. * @param dir The directory to list. - * @param filter_cb Callback called from another thread. - * @param main_cb Callback called from the main loop for each accepted file. - * @param done_cb Callback called from the main loop after the contents of the directory has been listed. - * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. + * @param filter_cb Callback used to decide if the file will be passed to main_cb + * @param main_cb Callback called for each listed file if it was not filtered. + * @param done_cb Callback called when the ls operation is done. + * @param error_cb Callback called when either the directory could not be opened or the operation has been canceled. * @param data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * - * eio_file_ls runs eina_file_ls in a separate thread using ecore_thread_feedback_run. This prevents - * any blocking in your apps. + * This function is responsible for listing the content of a directory without blocking your application. + * It's equivalent to the "ls" shell command. Every file will be passed to the + * filter_cb, so it's your job to decide if you want to pass the file to the + * main_cb or not. Return EINA_TRUE to pass it to the main_cb or EINA_FALSE to + * ignore it. */ EAPI Eio_File *eio_file_ls(const char *dir, Eio_Filter_Cb filter_cb, @@ -183,8 +200,8 @@ EAPI Eio_File *eio_file_ls(const char *dir, /** * @brief List contents of a directory without locking your app. * @param dir The directory to list. - * @param filter_cb Callback called from another thread. - * @param main_cb Callback called from the main loop for each accepted file. + * @param filter_cb Callback used to decide if the file will be passed to main_cb + * @param main_cb Callback called from the main loop for each accepted file (not filtered). * @param done_cb Callback called from the main loop after the contents of the directory has been listed. * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. * @param data Unmodified user data passed to callbacks @@ -192,6 +209,9 @@ EAPI Eio_File *eio_file_ls(const char *dir, * * eio_file_direct_ls runs eina_file_direct_ls in a separate thread using * ecore_thread_feedback_run. This prevents any blocking in your apps. + * Every file will be passed to the filter_cb, so it's your job to decide if you + * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to + * the main_cb or EINA_FALSE to ignore it. */ EAPI Eio_File *eio_file_direct_ls(const char *dir, Eio_Filter_Direct_Cb filter_cb, @@ -203,15 +223,17 @@ EAPI Eio_File *eio_file_direct_ls(const char *dir, /** * @brief List content of a directory without locking your app. * @param dir The directory to list. - * @param filter_cb Callback called from another thread. - * @param main_cb Callback called from the main loop for each accepted file. + * @param filter_cb Callback used to decide if the file will be passed to main_cb + * @param main_cb Callback called from the main loop for each accepted file (not filtered). * @param done_cb Callback called from the main loop after the contents of the directory has been listed. * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. * @param data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * - * eio_file_stat_ls() runs eina_file_stat_ls() in a separate thread using - * ecore_thread_feedback_run. This prevents any blocking in your apps. + * Every file will be passed to the filter_cb, so it's your job to decide if you + * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to + * the main_cb or EINA_FALSE to ignore it. + * */ EAPI Eio_File *eio_file_stat_ls(const char *dir, Eio_Filter_Direct_Cb filter_cb, @@ -223,8 +245,8 @@ EAPI Eio_File *eio_file_stat_ls(const char *dir, /** * @brief List the content of a directory and all it's sub-content asynchronously * @param dir The directory to list. - * @param filter_cb Callback called from another thread. - * @param main_cb Callback called from the main loop for each accepted file. + * @param filter_cb Callback used to decide if the file will be passed to main_cb + * @param main_cb Callback called from the main loop for each accepted file (not filtered). * @param done_cb Callback called from the main loop after the contents of the directory has been listed. * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. * @param data Unmodified user data passed to callbacks @@ -232,6 +254,10 @@ EAPI Eio_File *eio_file_stat_ls(const char *dir, * * eio_dir_stat_ls() runs eina_file_stat_ls() recursively in a separate thread using * ecore_thread_feedback_run. This prevents any blocking in your apps. + * Every file will be passed to the + * filter_cb, so it's your job to decide if you want to pass the file to the + * main_cb or not. Return EINA_TRUE to pass it to the main_cb or EINA_FALSE to + * ignore it. */ EAPI Eio_File *eio_dir_stat_ls(const char *dir, Eio_Filter_Dir_Cb filter_cb, @@ -243,8 +269,8 @@ EAPI Eio_File *eio_dir_stat_ls(const char *dir, /** * @brief List the content of a directory and all it's sub-content asynchronously * @param dir The directory to list. - * @param filter_cb Callback called from another thread. - * @param main_cb Callback called from the main loop for each accepted file. + * @param filter_cb Callback used to decide if the file will be passed to main_cb + * @param main_cb Callback called from the main loop for each accepted file (not filtered). * @param done_cb Callback called from the main loop after the contents of the directory has been listed. * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. * @param data Unmodified user data passed to callbacks @@ -252,6 +278,9 @@ EAPI Eio_File *eio_dir_stat_ls(const char *dir, * * eio_dir_direct_ls() runs eina_file_direct_ls() recursively in a separate thread using * ecore_thread_feedback_run. This prevents any blocking in your apps. + * Every file will be passed to the filter_cb, so it's your job to decide if you + * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to + * the main_cb or EINA_FALSE to ignore it. */ EAPI Eio_File *eio_dir_direct_ls(const char *dir, Eio_Filter_Dir_Cb filter_cb, @@ -279,12 +308,13 @@ EAPI Eio_File *eio_file_direct_stat(const char *path, * @brief Change right of a path. * @param path The directory path to change access right. * @param mode The permission to set, follow (mode & ~umask & 0777). - * @param done_cb Callback called from the main loop when the directory has been created. - * @param error_cb Callback called from the main loop when the directory failed to be created or has been canceled. - * @param data Unmodified user data passed to callbacks + * @param done_cb Callback called when the operation is completed. + * @param error_cb Callback called from if something goes wrong. + * @param data Unmodified user data passed to callbacks. * @return A reference to the I/O operation. * - * eio_file_chmod calls chmod in another thread. This prevents any blocking in your apps. + * Set a new permission of a path changing it to the mode passed as argument. + * It's equivalent to the chmod command. */ EAPI Eio_File *eio_file_chmod(const char *path, mode_t mode, @@ -297,13 +327,13 @@ EAPI Eio_File *eio_file_chmod(const char *path, * @param path The directory path to change owner. * @param user The new user to set (can be NULL). * @param group The new group to set (can be NULL). - * @param done_cb Callback called from the main loop when the directory has been created. - * @param error_cb Callback called from the main loop when the directory failed to be created or has been canceled. + * @param done_cb Callback called when the operation is completed. + * @param error_cb Callback called from if something goes wrong. * @param data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * - * eio_file_chown determines the uid/gid that correspond to both user and group string and then calls chown. This prevents any blocking in your apps by running - * the operation from another thread. The string can be the name of a user, the name of a group, or a UID. + * This function will change the owner of a path, setting it to the user and + * group passed as argument. It's equivalent to the chown shell command. */ EAPI Eio_File *eio_file_chown(const char *path, const char *user, @@ -315,12 +345,12 @@ EAPI Eio_File *eio_file_chown(const char *path, /** * @brief Unlink a file/directory. * @param path The path to unlink. - * @param done_cb Callback called from the main loop when the directory has been created. - * @param error_cb Callback called from the main loop when the directory failed to be created or has been canceled. - * @param data Unmodified user data passed to callbacks + * @param done_cb Callback called when the operation is completed. + * @param error_cb Callback called from if something goes wrong. + * @param data Unmodified user data passed to callbacks. * @return A reference to the I/O operation. * - * eio_file_unlink calls unlink in another thread. This prevents any blocking in your apps. + * This function will erase a file. */ EAPI Eio_File *eio_file_unlink(const char *path, Eio_Done_Cb done_cb, @@ -331,12 +361,12 @@ EAPI Eio_File *eio_file_unlink(const char *path, * @brief Create a new directory. * @param path The directory path to create. * @param mode The permission to set, follow (mode & ~umask & 0777). - * @param done_cb Callback called from the main loop when the directory has been created. - * @param error_cb Callback called from the main loop when the directory failed to be created or has been canceled. + * @param done_cb Callback called when the operation is completed. + * @param error_cb Callback called from if something goes wrong. * @param data Unmodified user data passed to callbacks * @return A reference to the I/O operation. * - * eio_file_mkdir calls mkdir in another thread. This prevents any blocking in your apps. + * Creates a new directory using the mode provided. */ EAPI Eio_File *eio_file_mkdir(const char *path, mode_t mode, @@ -398,6 +428,9 @@ EAPI Eio_File *eio_file_copy(const char *source, * It will try first to rename the directory, if not it will try to use splice * if possible, if not it will fallback to mmap/write. * It will try to preserve access right, but not user/group identity. + * Every file will be passed to the filter_cb, so it's your job to decide if you + * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to + * the main_cb or EINA_FALSE to ignore it. * * @note if a rename occur, the filter callback will not be called. */ @@ -422,6 +455,9 @@ EAPI Eio_File *eio_dir_move(const char *source, * This function will copy a directory and all it's content from source to dest. * It will try to use splice if possible, if not it will fallback to mmap/write. * It will try to preserve access right, but not user/group identity. + * Every file will be passed to the filter_cb, so it's your job to decide if you + * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to + * the main_cb or EINA_FALSE to ignore it. */ EAPI Eio_File *eio_dir_copy(const char *source, const char *dest, @@ -441,6 +477,9 @@ EAPI Eio_File *eio_dir_copy(const char *source, * @param data Unmodified user data passed to callbacks * * This function will remove a directory and all it's content. + * Every file will be passed to the filter_cb, so it's your job to decide if you + * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to + * the main_cb or EINA_FALSE to ignore it. */ EAPI Eio_File *eio_dir_unlink(const char *path, Eio_Filter_Direct_Cb filter_cb, @@ -458,6 +497,8 @@ EAPI Eio_File *eio_dir_unlink(const char *path, * * @brief A set of function to manipulate data associated with a specific file * + * The functions provided by this API are responsible to manage Extended + * attribute files. Like file authors, character encoding, checksum, etc. * @{ */ @@ -781,18 +822,20 @@ static inline Eina_Bool eio_file_is_lnk(const Eina_Stat *stat); * @brief This function help manipulating file asynchronously. * * This set of function work on top of Eina_File and Ecore_Thread to - * never block when reading the content of a file. + * do basic operations in a file, like openning, closing and mapping a file to + * memory. * @{ */ /** * @brief Assynchronously open a file. * @param name The file to open. - * @param shared If it's an shm file. + * @param shared If it's a shared memory file. * @param open_cb Callback called in the main loop when the file has been successfully opened. * @param error_cb Callback called in the main loop when the file couldn't be opened. * @param data Unmodified user data passed to callbacks - * @return NULL in case of a failure. + * @return Pointer to the file if successfull or NULL otherwise. + * */ EAPI Eio_File *eio_file_open(const char *name, Eina_Bool shared, Eio_Open_Cb open_cb, @@ -805,7 +848,7 @@ EAPI Eio_File *eio_file_open(const char *name, Eina_Bool shared, * @param done_cb Callback called in the main loop when the file has been successfully closed. * @param error_cb Callback called in the main loop when the file couldn't be closed. * @param data Unmodified user data passed to callbacks - * @return NULL in case of a failure. + * @return Pointer to the file if successfull or NULL otherwise. */ EAPI Eio_File *eio_file_close(Eina_File *f, Eio_Done_Cb done_cb, @@ -820,7 +863,7 @@ EAPI Eio_File *eio_file_close(Eina_File *f, * @param map_cb Callback called in the main loop when the file has been successfully mapped. * @param error_cb Callback called in the main loop when the file can't be mapped. * @param data Unmodified user data passed to callbacks - * @return NULL in case of a failure. + * @return Pointer to the file if successfull or NULL otherwise. * * The container of the Eio_File is the Eina_File. */ @@ -841,7 +884,7 @@ EAPI Eio_File *eio_file_map_all(Eina_File *f, * @param map_cb Callback called in the main loop when the file has been successfully mapped. * @param error_cb Callback called in the main loop when the file can't be mapped. * @param data Unmodified user data passed to callbacks - * @return NULL in case of a failure. + * @return Pointer to the file if successfull or NULL otherwise. * * The container of the Eio_File is the Eina_File. */ @@ -861,13 +904,13 @@ EAPI Eio_File *eio_file_map_new(Eina_File *f, /** * @defgroup Eio_Eet Eio asynchronous API for Eet file. * - * @brief This set of functions help use Eet asynchronously + * @brief This set of functions help in the asynchronous use of Eet * * @{ */ /** - * Open an eet file on disk, and returns a handle to it asynchronously. + * @brief Open an eet file on disk, and returns a handle to it asynchronously. * @param filename The file path to the eet file. eg: @c "/tmp/file.eet". * @param mode The mode for opening. Either EET_FILE_MODE_READ, * EET_FILE_MODE_WRITE or EET_FILE_MODE_READ_WRITE. @@ -884,7 +927,7 @@ EAPI Eio_File *eio_eet_open(const char *filename, Eio_Error_Cb error_cb, const void *data); /** - * Close an eet file handle and flush pending writes asynchronously. + * @brief Close an eet file handle and flush pending writes asynchronously. * @param ef A valid eet file handle. * @param done_cb Callback called from the main loop when the file has been closed. * @param error_cb Callback called in the main loop when the file can't be closed. @@ -901,7 +944,7 @@ EAPI Eio_File *eio_eet_close(Eet_File *ef, const void *data); /** - * Sync content of an eet file handle, flushing pending writes asynchronously. + * @brief Sync content of an eet file handle, flushing pending writes asynchronously. * @param ef A valid eet file handle. * @param done_cb Callback called from the main loop when the file has been synced. * @param error_cb Callback called in the main loop when the file can't be synced. @@ -917,7 +960,7 @@ EAPI Eio_File *eio_eet_sync(Eet_File *ef, const void *data); /** - * Write a data structure from memory and store in an eet file + * @brief Write a data structure from memory and store in an eet file * using a cipher asynchronously. * @param ef The eet file handle to write to. * @param edd The data descriptor to use when encoding. @@ -941,7 +984,7 @@ EAPI Eio_File *eio_eet_data_write_cipher(Eet_File *ef, const void *user_data); /** - * Read a data structure from an eet file and decodes it using a cipher asynchronously. + * @brief Read a data structure from an eet file and decodes it using a cipher asynchronously. * @param ef The eet file handle to read from. * @param edd The data descriptor handle to use when decoding. * @param name The key the data is stored under in the eet file. @@ -960,7 +1003,7 @@ EAPI Eio_File *eio_eet_data_read_cipher(Eet_File *ef, const void *data); /** - * Write image data to the named key in an eet file asynchronously. + * @brief Write image data to the named key in an eet file asynchronously. * @param ef A valid eet file handle opened for writing. * @param name Name of the entry. eg: "/base/file_i_want". * @param cipher_key The key to use as cipher. @@ -991,7 +1034,7 @@ EAPI Eio_File *eio_eet_data_image_write_cipher(Eet_File *ef, const void *user_data); /** - * Read a specified entry from an eet file and return data + * @brief Read a specified entry from an eet file and return data * @param ef A valid eet file handle opened for reading. * @param name Name of the entry. eg: "/base/file_i_want". * @param done_cb Callback called from the main loop when the data has been read. @@ -1006,7 +1049,7 @@ EAPI Eio_File *eio_eet_read_direct(Eet_File *ef, const void *data); /** - * Read a specified entry from an eet file and return data + * @brief Read a specified entry from an eet file and return data * @param ef A valid eet file handle opened for reading. * @param name Name of the entry. eg: "/base/file_i_want". * @param cipher_key The key to use as cipher. @@ -1023,7 +1066,7 @@ EAPI Eio_File *eio_eet_read_cipher(Eet_File *ef, const void *data); /** - * Write a specified entry to an eet file handle using a cipher. + * @brief Write a specified entry to an eet file handle using a cipher. * @param ef A valid eet file handle opened for writing. * @param name Name of the entry. eg: "/base/file_i_want". * @param write_data Pointer to the data to be stored. @@ -1093,7 +1136,8 @@ struct _Eio_Monitor_Event /** * @brief Adds a file/directory to monitor (inotify mechanism) * @param path file/directory to monitor - * @return NULL in case of a failure. + * @return NULL in case of a failure or a pointer to the monitor in case of + * success. * * This function will add the given path to its internal * list of files to monitor. It utilizes the inotify mechanism @@ -1102,12 +1146,15 @@ struct _Eio_Monitor_Event EAPI Eio_Monitor *eio_monitor_add(const char *path); /** + * @brief Adds a file/directory to monitor * @param path file/directory to monitor - * @return NULL in case of a failure. - * Does the same thing as eio_monitor_add() but - * expects a stringshared string. + * @return NULL in case of a failure or a pointer to the monitor in case of + * success. * @warning Do NOT pass non-stringshared strings to this function! * If you don't know what this means, use eio_monitor_add(). + * + * This fuction is just like eio_monitor_add(), however the string passed by + * argument must be created using eina_stringshare_add(). */ EAPI Eio_Monitor *eio_monitor_stringshared_add(const char *path);