From: gastal Date: Wed, 22 Jun 2011 19:48:27 +0000 (+0000) Subject: Eina: Eina error documentation improvement. X-Git-Tag: 2.0_alpha~69^2~35 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=0e5bd1d5d943bff306f1c04543adff2db156d174;p=framework%2Fuifw%2Feina.git Eina: Eina error documentation improvement. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/eina@60605 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- diff --git a/src/examples/Makefile.am b/src/examples/Makefile.am index e8b14b4..85748bf 100644 --- a/src/examples/Makefile.am +++ b/src/examples/Makefile.am @@ -14,6 +14,7 @@ SRCS = \ eina_accessor_01.c \ eina_array_01.c \ eina_array_02.c \ + eina_error_01.c \ eina_hash_01.c \ eina_hash_02.c \ eina_iterator_01.c \ @@ -37,6 +38,7 @@ pkglib_PROGRAMS += \ eina_accessor_01 \ eina_array_01 \ eina_array_02 \ + eina_error_01 \ eina_hash_01 \ eina_hash_02 \ eina_iterator_01 \ diff --git a/src/examples/eina_error_01.c b/src/examples/eina_error_01.c new file mode 100644 index 0000000..90e845d --- /dev/null +++ b/src/examples/eina_error_01.c @@ -0,0 +1,80 @@ +//Compile with: +//gcc -g `pkg-config --cflags --libs eina` eina_error_01.c -o eina_error_01 + +#include +#include + +#include + +Eina_Error MY_ERROR_NEGATIVE; +Eina_Error MY_ERROR_NULL; + +void *data_new() +{ + eina_error_set(0); + + eina_error_set(MY_ERROR_NULL); + return NULL; +} + +int test(int n) +{ + eina_error_set(0); + + if (n < 0) + { + eina_error_set(MY_ERROR_NEGATIVE); + return 0; + } + + return 1; +} + +int main(void) +{ + void *data; + + if (!eina_init()) + { + printf ("Error during the initialization of eina_error module\n"); + return EXIT_FAILURE; + } + + MY_ERROR_NEGATIVE = eina_error_msg_static_register("Negative number"); + MY_ERROR_NULL = eina_error_msg_static_register("NULL pointer"); + + data = data_new(); + if (!data) + { + Eina_Error err; + + err = eina_error_get(); + if (err) + printf("Error during memory allocation: %s\n", + eina_error_msg_get(err)); + } + + if (!test(0)) + { + Eina_Error err; + + err = eina_error_get(); + if (err) + printf("Error during test function: %s\n", + eina_error_msg_get(err)); + } + + if (!test(-1)) + { + Eina_Error err; + + err = eina_error_get(); + if (err) + printf("Error during test function: %s\n", + eina_error_msg_get(err)); + } + + eina_shutdown(); + + return EXIT_SUCCESS; +} \ No newline at end of file diff --git a/src/include/eina_error.h b/src/include/eina_error.h index c6736a9..5ca1fbe 100644 --- a/src/include/eina_error.h +++ b/src/include/eina_error.h @@ -27,16 +27,9 @@ /** * @page tutorial_error_page Error Tutorial * - * @section tutorial_error_introduction Introduction - * - * The Eina error module provides a way to manage errors in a simple - * but powerful way in libraries and modules. It is also used in Eina - * itself. Similar to libC's @c errno and strerror() facilities, this - * is extensible and recommended for other libraries and applications. - * * @section tutorial_error_registering_msg Registering messages * - * The error module can provide a system that mimic the errno system + * The error module can provide a system that mimics the errno system * of the C standard library. It consists in 2 parts: * * @li a way of registering new messages with @@ -53,85 +46,7 @@ * * Here is an example of use: * - * @code - * #include - * #include - * - * #include - * - * Eina_Error MY_ERROR_NEGATIVE; - * Eina_Error MY_ERROR_NULL; - * - * voi *data_new() - * { - * eina_error_set(0); - * - * eina_error_set(MY_ERROR_NULL); - * return NULL; - * } - * - * int test(int n) - * { - * eina_error_set(0); - * - * if (n < 0) - * { - * eina_error_set(MY_ERROR_NEGATIVE); - * return 0; - * } - * - * return 1; - * } - * - * int main(void) - * { - * void *data; - * - * if (!eina_init()) - * { - * printf ("Error during the initialization of eina_error module\n"); - * return EXIT_FAILURE; - * } - * - * MY_ERROR_NEGATIVE = eina_error_msg_register("Negative number"); - * MY_ERROR_NULL = eina_error_msg_register("NULL pointer"); - - * data = data_new(); - * if (!data) - * { - * Eina_Error err; - * - * err = eina_error_get(); - * if (err) - * printf("Error during memory allocation: %s\n", - * eina_error_msg_get(err)); - * } - * - * if (!test(0)) - * { - * Eina_Error err; - * - * err = eina_error_get(); - * if (err) - * printf("Error during test function: %s\n", - * eina_error_msg_get(err)); - * } - * - * if (!test(-1)) - * { - * Eina_Error err; - * - * err = eina_error_get(); - * if (err) - * printf("Error during test function: %s\n", - * eina_error_msg_get(err)); - * } - * - * eina_shutdown(); - * - * return EXIT_SUCCESS; - * } - * @endcode + * @include eina_error_01.c * * Of course, instead of printf(), eina_log_print() can be used to * have beautiful error messages. @@ -142,13 +57,13 @@ * * @brief These functions provide error management for projects. * - * To use the error system Eina must be initialized with eina_init() - * and later shut down with eina_shutdown(). Error codes are - * registered with eina_error_msg_register() and converted from - * identifier to original message string with eina_error_msg_get(). + * The Eina error module provides a way to manage errors in a simple but + * powerful way in libraries and modules. It is also used in Eina itself. + * Similar to libC's @c errno and strerror() facilities, this is extensible and + * recommended for other libraries and applications. * - * Logging functions are not in eina_error anymore, see - * eina_log_print() instead. + * A simple example of how to use this can be seen @ref tutorial_error_page + * "here". * * @{ */ @@ -217,7 +132,7 @@ EAPI Eina_Error eina_error_msg_static_register(const char *msg) EINA_ARG_NONNUL * @param error The Eina_Error to change the message of * @param msg The description of the error. This string will be * duplicated only if the error was registered with @ref eina_error_msg_register - * otherwise it must remain intact for the duration + * otherwise it must remain intact for the duration. * @return EINA_TRUE if successful, EINA_FALSE on error * * This function modifies the message associated with @p error and changes @@ -247,6 +162,9 @@ EAPI Eina_Error eina_error_get(void); * * This function sets the last error identifier. The last error can be * retrieved with eina_error_get(). + * + * @note This is also used to clear previous errors, in that case @p err should + * be @c 0. */ EAPI void eina_error_set(Eina_Error err);