From 554efc015a79f40a98fef7beae1e7d5d3843c0bb Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 10 Oct 2014 11:45:02 +0200 Subject: [PATCH 01/55] evas: add documentation for Evas_Version structure. --- src/lib/evas/Evas_Common.h | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h index 6826c79b72..f9a517d8cf 100644 --- a/src/lib/evas/Evas_Common.h +++ b/src/lib/evas/Evas_Common.h @@ -5,12 +5,34 @@ #define EVAS_VERSION_MAJOR EFL_VERSION_MAJOR #define EVAS_VERSION_MINOR EFL_VERSION_MINOR +/** + * @typedef Evas_Version + * + * This is the Evas version information structure that can be used at + * runtime to detect which version of evas is being used and adapt + * appropriately as follows for example: + * + * @code + * #if defined(EVAS_VERSION_MAJOR) && (EVAS_VERSION_MAJOR >= 1) && defined(EVAS_VERSION_MINOR) && (EVAS_VERSION_MINOR > 0) + * printf("Evas version: %i.%i.%i\n", + * evas_version->major, + * evas_version->minor, + * evas_version->micro); + * if (evas_version->revision > 0) + * { + * printf(" Built from Git revision # %i\n", evas_version->revision); + * } + * #endif + * @endcode + * + */ + typedef struct _Evas_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Evas is built from) */ } Evas_Version; EAPI extern Evas_Version * evas_version; From 0bbcef65aba7e3a83fd3ba95740739467b19a0c9 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 10 Oct 2014 12:01:42 +0200 Subject: [PATCH 02/55] ecore: add documentation for Ecore_Version structure. --- src/lib/ecore/Ecore_Common.h | 29 +++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/src/lib/ecore/Ecore_Common.h b/src/lib/ecore/Ecore_Common.h index b45af6ce1f..8ed1742a58 100644 --- a/src/lib/ecore/Ecore_Common.h +++ b/src/lib/ecore/Ecore_Common.h @@ -70,12 +70,33 @@ EAPI int ecore_shutdown(void); #define ECORE_VERSION_MAJOR EFL_VERSION_MAJOR #define ECORE_VERSION_MINOR EFL_VERSION_MINOR +/** + * @typedef Ecore_Version + * + * This is the Ecore version information structure that can be used at + * runtime to detect which version of ecore is being used and adapt + * appropriately as follows for example: + * + * @code + * #if defined(ECORE_VERSION_MAJOR) && (ECORE_VERSION_MAJOR >= 1) && defined(ECORE_VERSION_MINOR) && (ECORE_VERSION_MINOR > 0) + * printf("Ecore version: %i.%i.%i\n", + * ecore_version->major, + * ecore_version->minor, + * ecore_version->micro); + * if (ecore_version->revision > 0) + * { + * printf(" Built from Git revision # %i\n", ecore_version->revision); + * } + * #endif + * @endcode + * + */ typedef struct _Ecore_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Ecore is built from) */ } Ecore_Version; EAPI extern Ecore_Version *ecore_version; From 3032ebc3e2ae8d85c01adad7fc8815259b843706 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 10 Oct 2014 12:14:46 +0200 Subject: [PATCH 03/55] ecore_x: add documentation for Ecore_X_Version structure. --- src/lib/ecore_x/Ecore_X.h | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/lib/ecore_x/Ecore_X.h b/src/lib/ecore_x/Ecore_X.h index 2db94da391..c3f0726b2b 100644 --- a/src/lib/ecore_x/Ecore_X.h +++ b/src/lib/ecore_x/Ecore_X.h @@ -28,13 +28,16 @@ #define ECORE_X_VERSION_MAJOR EFL_VERSION_MAJOR #define ECORE_X_VERSION_MINOR EFL_VERSION_MINOR - +/** + * @typedef Ecore_X_Version + * Represents the current version of Ecore_X + */ typedef struct _Ecore_X_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Ecore_X is built from) */ } Ecore_X_Version; EAPI extern Ecore_X_Version *ecore_x_version; From ad41ba380e644de3536a8d8e4519c2612ac3a0a8 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 10 Oct 2014 12:15:36 +0200 Subject: [PATCH 04/55] eeze: add documentation for Eeze_Version structure. --- src/lib/eeze/Eeze.h | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/lib/eeze/Eeze.h b/src/lib/eeze/Eeze.h index d63c54413f..be9f9a9a9b 100644 --- a/src/lib/eeze/Eeze.h +++ b/src/lib/eeze/Eeze.h @@ -289,13 +289,16 @@ typedef struct Eeze_Udev_Watch Eeze_Udev_Watch; #define EEZE_VERSION_MAJOR EFL_VERSION_MAJOR #define EEZE_VERSION_MINOR EFL_VERSION_MINOR - + /** + * @typedef Eeeze_Version + * Represents the current version of Eeze + */ typedef struct _Eeze_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Eeze is built from) */ } Eeze_Version; EAPI extern Eeze_Version *eeze_version; From f078d163916cf655c624eca2f852a09749040382 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 10 Oct 2014 12:16:24 +0200 Subject: [PATCH 05/55] efreet: add documentation for Efreet_Version structure. --- src/lib/efreet/Efreet.h | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/lib/efreet/Efreet.h b/src/lib/efreet/Efreet.h index e2360ee0e7..419e5ff531 100644 --- a/src/lib/efreet/Efreet.h +++ b/src/lib/efreet/Efreet.h @@ -106,13 +106,16 @@ extern "C" { #define EFREET_VERSION_MAJOR EFL_VERSION_MAJOR #define EFREET_VERSION_MINOR EFL_VERSION_MINOR - + /** + * @typedef Efreet_Version + * Represents the current version of Efreet + */ typedef struct _Efreet_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Efreet is built from) */ } Efreet_Version; EAPI extern Efreet_Version *efreet_version; From 251164ad72e9a0e951d06e6a262141c465ff5689 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 10 Oct 2014 12:17:12 +0200 Subject: [PATCH 06/55] ethumb: add documentation for Ethumb_Version structure. --- src/lib/ethumb/Ethumb.h | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/lib/ethumb/Ethumb.h b/src/lib/ethumb/Ethumb.h index 4f91433588..6a1bd4087f 100644 --- a/src/lib/ethumb/Ethumb.h +++ b/src/lib/ethumb/Ethumb.h @@ -36,13 +36,16 @@ extern "C" { #define ETHUMB_VERSION_MAJOR EFL_VERSION_MAJOR #define ETHUMB_VERSION_MINOR EFL_VERSION_MINOR - + /** + * @typedef Ethumb_Version + * Represents the current version of Ethumb + */ typedef struct _Ethumb_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Ethumb is built from) */ } Ethumb_Version; EAPI extern Ethumb_Version *ethumb_version; From f15d4627377fe5288baf864ba6df1f3c6ce26f98 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 10 Oct 2014 12:20:24 +0200 Subject: [PATCH 07/55] eldbus: add documentation for Eldbus_Version structure. --- src/lib/eldbus/Eldbus.h | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/lib/eldbus/Eldbus.h b/src/lib/eldbus/Eldbus.h index 478fcea92f..220d4ecbb9 100644 --- a/src/lib/eldbus/Eldbus.h +++ b/src/lib/eldbus/Eldbus.h @@ -129,12 +129,16 @@ extern "C" { #define ELDBUS_ERROR_PENDING_CANCELED "org.enlightenment.DBus.Canceled" #define ELDBUS_ERROR_PENDING_TIMEOUT "org.freedesktop.DBus.Error.NoReply" +/** + * @typedef Eldbus_Version + * Represents the current version of Eldbus + */ typedef struct _Eldbus_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Eldbus is built from) */ } Eldbus_Version; EAPI extern const Eldbus_Version * eldbus_version; From 020f5012652b3df8f643a2bbe3c917c068493082 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 10 Oct 2014 12:20:45 +0200 Subject: [PATCH 08/55] embryo: add documentation for Embryo_Version structure. --- src/lib/embryo/Embryo.h | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/src/lib/embryo/Embryo.h b/src/lib/embryo/Embryo.h index 923afe73aa..413c38bf1a 100644 --- a/src/lib/embryo/Embryo.h +++ b/src/lib/embryo/Embryo.h @@ -370,13 +370,17 @@ extern "C" { #define EMBRYO_VERSION_MAJOR EFL_VERSION_MAJOR #define EMBRYO_VERSION_MINOR EFL_VERSION_MINOR - + + /** + * @typedef Embryo_Version + * Represents the current version of Embryo + */ typedef struct _Embryo_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Embryo is built from) */ } Embryo_Version; EAPI extern Embryo_Version *embryo_version; From 1e64aed04a51b94e7f8a946a83acf85a6f1b442b Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 10 Oct 2014 12:21:04 +0200 Subject: [PATCH 09/55] emotion: add documentation for Emotion_Version structure. --- src/lib/emotion/Emotion.h | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/lib/emotion/Emotion.h b/src/lib/emotion/Emotion.h index b07cbd3062..bb41cbeaf9 100644 --- a/src/lib/emotion/Emotion.h +++ b/src/lib/emotion/Emotion.h @@ -272,13 +272,16 @@ extern "C" { #define EMOTION_VERSION_MAJOR EFL_VERSION_MAJOR #define EMOTION_VERSION_MINOR EFL_VERSION_MINOR - + /** + * @typedef Emotion_Version + * Represents the current version of Emotion + */ typedef struct _Emotion_Version { - int major; - int minor; - int micro; - int revision; + int major; /** < major (binary or source incompatible changes) */ + int minor; /** < minor (new features, bugfixes, major improvements version) */ + int micro; /** < micro (bugfix, internal improvements, no new features version) */ + int revision; /** < git revision (0 if a proper release or the git revision number Emotion is built from) */ } Emotion_Version; EAPI extern Emotion_Version *emotion_version; From c65a1d17c21050849ca22480b877c5a8e4d9794e Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 10 Oct 2014 12:44:03 +0200 Subject: [PATCH 10/55] evas: fix typo in documentation and document the return value of evas_device_add. --- src/lib/evas/Evas_Common.h | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h index f9a517d8cf..6dfa5113cf 100644 --- a/src/lib/evas/Evas_Common.h +++ b/src/lib/evas/Evas_Common.h @@ -1323,10 +1323,12 @@ EAPI void evas_render_updates_free(Eina_List *updates); * * @param e The canvas to create the device node for. * - * Adds a new device nod to the given canvas @p e. All devices created as + * Adds a new device node to the given canvas @p e. All devices created as * part of the canvas @p e will automatically be deleted when the canvas * is freed. * + * @return the device node created or NULL if an error occured. + * * @see evas_device_del * @since 1.8 */ From 55a1edbb7840ee7658e063c9f0611766b413bfbc Mon Sep 17 00:00:00 2001 From: Ghislain Loaec Date: Tue, 30 Sep 2014 16:07:51 +0200 Subject: [PATCH 11/55] eina: Eina_Rectangle API documentation --- src/lib/eina/eina_inline_rectangle.x | 124 ------------ src/lib/eina/eina_rectangle.h | 277 +++++++++++++++++++++++++-- 2 files changed, 261 insertions(+), 140 deletions(-) diff --git a/src/lib/eina/eina_inline_rectangle.x b/src/lib/eina/eina_inline_rectangle.x index e25942bd46..fafe1394a6 100644 --- a/src/lib/eina/eina_inline_rectangle.x +++ b/src/lib/eina/eina_inline_rectangle.x @@ -19,61 +19,18 @@ #ifndef EINA_INLINE_RECTANGLE_H__ #define EINA_INLINE_RECTANGLE_H__ -/** - * @addtogroup Eina_Rectangle_Group Rectangle - * - * @brief These functions provide rectangle management. - * - * @{ - */ - -/** - * @brief Check if the given spans intersect. - * - * @param c1 The column of the first span. - * @param l1 The length of the first span. - * @param c2 The column of the second span. - * @param l2 The length of the second span. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if the given spans intersect, #EINA_FALSE - * otherwise. - */ static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) { return (!(((c2 + l2) <= c1) || (c2 >= (c1 + l1)))); } -/** - * @brief Check if the given rectangle is empty. - * - * @param r The rectangle to check. - * @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if @p r is empty, #EINA_FALSE - * otherwise. No check is done on @p r, so it must be a valid - * rectangle. - */ static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) { return ((r->w < 1) || (r->h < 1)) ? EINA_TRUE : EINA_FALSE; } -/** - * @brief Set the coordinates and size of the given rectangle. - * - * @param r The rectangle. - * @param x The top-left x coordinate of the rectangle. - * @param y The top-left y coordinate of the rectangle. - * @param w The width of the rectangle. - * @param h The height of the rectangle. - * - * This function sets its top-left x coordinate to @p x, its top-left - * y coordinate to @p y, its width to @p w and its height to @p h. No - * check is done on @p r, so it must be a valid rectangle. - */ static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) { @@ -83,85 +40,30 @@ eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) r->h = h; } -/** - * @brief Check if the given rectangles intersect. - * - * @param r1 The first rectangle. - * @param r2 The second rectangle. - * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if @p r1 and @p r2 intersect, #EINA_FALSE - * otherwise. No check is done on @p r1 and @p r2, so they must be valid - * rectangles. - */ static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) { return (eina_spans_intersect(r1->x, r1->w, r2->x, r2->w) && eina_spans_intersect(r1->y, r1->h, r2->y, r2->h)) ? EINA_TRUE : EINA_FALSE; } -/** - * @brief Check if the given x-coordinate is in the rectangle . - * - * @param r The rectangle. - * @param x The x coordinate. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if @p x is in @p r with respect to - * the horizontal direction, #EINA_FALSE otherwise. No check is done - * on @p r, so it must be a valid rectangle. - */ static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) { return ((x >= r->x) && (x < (r->x + r->w))) ? EINA_TRUE : EINA_FALSE; } -/** - * @brief Check if the given y-coordinate is in the rectangle . - * - * @param r The rectangle. - * @param y The y coordinate. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if @p y is in @p r with respect to - * the vertical direction, #EINA_FALSE otherwise. No check is done - * on @p r, so it must be a valid rectangle. - */ static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) { return ((y >= r->y) && (y < (r->y + r->h))) ? EINA_TRUE : EINA_FALSE; } -/** - * @brief Check if the given point is in the rectangle . - * - * @param r The rectangle. - * @param x The x coordinate of the point. - * @param y The y coordinate of the point. - * @return #EINA_TRUE on success, #EINA_FALSE otherwise. - * - * This function returns #EINA_TRUE if the point of coordinate (@p x, - * @p y) is in @p r, #EINA_FALSE otherwise. No check is done on @p r, - * so it must be a valid rectangle. - */ static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r, int x, int y) { return (eina_rectangle_xcoord_inside(r, x) && eina_rectangle_ycoord_inside(r, y)) ? EINA_TRUE : EINA_FALSE; } -/** - * @brief Get the union of two rectangles. - * - * @param dst The first rectangle. - * @param src The second rectangle. - * - * This function get the union of the rectangles @p dst and @p src. The - * result is stored in @p dst. No check is done on @p dst or @p src, - * so they must be valid rectangles. - */ static inline void eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) { @@ -185,18 +87,6 @@ eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) dst->h = src->y + src->h - dst->y; } -/** - * @brief Get the intersection of two rectangles. - * - * @param dst The first rectangle. - * @param src The second rectangle. - * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE - * otherwise. - * - * This function get the intersection of the rectangles @p dst and - * @p src. The result is stored in @p dst. No check is done on @p dst - * or @p src, so they must be valid rectangles. - */ static inline Eina_Bool eina_rectangle_intersection(Eina_Rectangle *dst, const Eina_Rectangle *src) { @@ -319,16 +209,6 @@ eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rect return EINA_TRUE; } -/** - * @brief Subtract two rectangles. - * - * @param thiz The minuend rectangle - * @param other The subtrahend rectangle - * - * This function subtract two rectangles. The difference is stored on @p out - * There will be at most four differences, use eina_rectangle_is_valid to - * confirm the number of differences. - */ static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectangle out[4]) { @@ -385,8 +265,4 @@ eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectan return EINA_TRUE; } -/** - * @} - */ - #endif diff --git a/src/lib/eina/eina_rectangle.h b/src/lib/eina/eina_rectangle.h index 8f5eead1de..55d370ff25 100644 --- a/src/lib/eina/eina_rectangle.h +++ b/src/lib/eina/eina_rectangle.h @@ -74,24 +74,269 @@ typedef enum { Eina_Packing_Bottom_Left_Skyline_Improved /**< optimized bottemleft skyline */ } Eina_Rectangle_Packing; +/** + * @brief Check if the given spans intersect. + * + * @param c1 The column of the first span. + * @param l1 The length of the first span. + * @param c2 The column of the second span. + * @param l2 The length of the second span. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if the given spans intersect, #EINA_FALSE + * otherwise. + */ static inline int eina_spans_intersect(int c1, int l1, int c2, int l2) EINA_WARN_UNUSED_RESULT; -static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; -static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) EINA_ARG_NONNULL(1); -static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; -static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; -static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; -static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r, int x, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; -static inline void eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2); -static inline Eina_Bool eina_rectangle_intersection(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; -static inline void eina_rectangle_rescale_in(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3); -static inline void eina_rectangle_rescale_out(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3); -static inline Eina_Bool eina_rectangle_is_valid(const Eina_Rectangle *r) EINA_ARG_NONNULL(1); -static inline Eina_Bool eina_rectangle_x_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); -static inline Eina_Bool eina_rectangle_y_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); -static inline Eina_Bool eina_rectangle_width_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); -static inline Eina_Bool eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); -static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectangle out[4]) EINA_ARG_NONNULL(1); +/** + * @brief Check if the given rectangle is empty. + * + * @param r The rectangle to check. + * @return #EINA_TRUE if the rectangle is empty, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p r is empty, #EINA_FALSE + * otherwise. No check is done on @p r, so it must be a valid + * rectangle. + */ +static inline Eina_Bool eina_rectangle_is_empty(const Eina_Rectangle *r) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Set the coordinates and size of the given rectangle. + * + * @param r The rectangle. + * @param x The top-left x coordinate of the rectangle. + * @param y The top-left y coordinate of the rectangle. + * @param w The width of the rectangle. + * @param h The height of the rectangle. + * + * This function sets its top-left x coordinate to @p x, its top-left + * y coordinate to @p y, its width to @p w and its height to @p h. No + * check is done on @p r, so it must be a valid rectangle. + */ +static inline void eina_rectangle_coords_from(Eina_Rectangle *r, int x, int y, int w, int h) EINA_ARG_NONNULL(1); + +/** + * @brief Check if the given rectangles intersect. + * + * @param r1 The first rectangle. + * @param r2 The second rectangle. + * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p r1 and @p r2 intersect, #EINA_FALSE + * otherwise. No check is done on @p r1 and @p r2, so they must be valid + * rectangles. + */ +static inline Eina_Bool eina_rectangles_intersect(const Eina_Rectangle *r1, const Eina_Rectangle *r2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Check if the given x-coordinate is in the rectangle . + * + * @param r The rectangle. + * @param x The x coordinate. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p x is in @p r with respect to + * the horizontal direction, #EINA_FALSE otherwise. No check is done + * on @p r, so it must be a valid rectangle. + */ +static inline Eina_Bool eina_rectangle_xcoord_inside(const Eina_Rectangle *r, int x) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Check if the given y-coordinate is in the rectangle . + * + * @param r The rectangle. + * @param y The y coordinate. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if @p y is in @p r with respect to + * the vertical direction, #EINA_FALSE otherwise. No check is done + * on @p r, so it must be a valid rectangle. + */ +static inline Eina_Bool eina_rectangle_ycoord_inside(const Eina_Rectangle *r, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Check if the given point is in the rectangle . + * + * @param r The rectangle. + * @param x The x coordinate of the point. + * @param y The y coordinate of the point. + * @return #EINA_TRUE on success, #EINA_FALSE otherwise. + * + * This function returns #EINA_TRUE if the point of coordinate (@p x, + * @p y) is in @p r, #EINA_FALSE otherwise. No check is done on @p r, + * so it must be a valid rectangle. + */ +static inline Eina_Bool eina_rectangle_coords_inside(const Eina_Rectangle *r, int x, int y) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Get the union of two rectangles. + * + * @param dst The first rectangle. + * @param src The second rectangle. + * + * This function get the union of the rectangles @p dst and @p src. The + * result is stored in @p dst. No check is done on @p dst or @p src, + * so they must be valid rectangles. + */ +static inline void eina_rectangle_union(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Get the intersection of two rectangles. + * + * @param dst The first rectangle. + * @param src The second rectangle. + * @return #EINA_TRUE if the rectangles intersect, #EINA_FALSE + * otherwise. + * + * This function get the intersection of the rectangles @p dst and + * @p src. The result is stored in @p dst. No check is done on @p dst + * or @p src, so they must be valid rectangles. + */ +static inline Eina_Bool eina_rectangle_intersection(Eina_Rectangle *dst, const Eina_Rectangle *src) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; + +/** + * @brief FIXME I am useless and used by no one + * + * @param in The inner rectangle. + * @param out The outer rectangle. + * @param res The resulting rectangle. + * + */ +static inline void eina_rectangle_rescale_in(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief FIXME I am useless and used by no one + * + * @param in The inner rectangle. + * @param out The outer rectangle. + * @param res The resulting rectangle. + * + */ +static inline void eina_rectangle_rescale_out(const Eina_Rectangle *out, const Eina_Rectangle *in, Eina_Rectangle *res) EINA_ARG_NONNULL(1, 2, 3); + +/** + * + * @brief Tells whether a rectangle is valid or not. + * + * @param r The rectangle + * @return #EINA_TRUE if the rectangle is valid, #EINA_FALSE otherwise. + * + * This function checks if both width and height attributes of the rectangle are + * positive integers. If so, the rectangle is considered valid, else the + * rectangle is invalid. + */ +static inline Eina_Bool eina_rectangle_is_valid(const Eina_Rectangle *r) EINA_ARG_NONNULL(1); + +/** + * + * @brief Gives the rectangle maximum x coordinate. + * + * @param thiz The rectangle + * @return the maximum x coordinate + * + * This function calculates the maximum x coordinate of the rectangle by summing + * the @p width with the current @p x coodinate of the rectangle. + */ +static inline int eina_rectangle_max_x(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1); + +/** + * + * @brief Gives the rectangle maximum y coordinate. + * + * @param thiz The rectangle + * @return the maximum y coordinate + * + * This function calculates the maximum y coordinate of the rectangle by summing + * the @p height with the current @p y coodinate of the rectangle. + */ +static inline int eina_rectangle_max_y(Eina_Rectangle *thiz) EINA_ARG_NONNULL(1); + +/** + * + * @brief Slices a rectangle vertically into two subrectangles starting from left edge + * + * @param thiz The rectangle to slice + * @param slice The sliced part of the rectangle + * @param remainder The left over part of the original rectangle after slice + * @param amount The x inner coordinate of the rectangle where to perform the + * slicing. + * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise + * + * Use this function if we must cut a rectangle vertically. The @p amount + * parameter defines the x inner coordinate where to do the cut, starting from + * the left edge of the rectangle. If the @p amount value is greater than the + * rectangle width, there will be not cut possible and #EINA_FALSE will be + * returned. + */ +static inline Eina_Bool eina_rectangle_x_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); + +/** + * + * @brief Slices a rectangle horizontally into two subrectangles starting from bottom edge + * + * @param thiz The rectangle to slice + * @param slice The sliced part of the rectangle + * @param remainder The left over part of the original rectangle after slice + * @param amount The y inner coordinate of the rectangle where to perform the + * slicing. + * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise + * + * Use this function if we must cut a rectangle horizontally. The @p amount + * parameter defines the y inner coordinate where to do the cut, starting from + * the bottom edge of the rectangle. If the @p amount value is greater than the + * rectangle width, there will be not cut possible and #EINA_FALSE will be + * returned. + */ +static inline Eina_Bool eina_rectangle_y_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); + +/** + * + * @brief Slices a rectangle vertically starting from right edge + * + * @param thiz The rectangle to slice + * @param slice The sliced part of the rectangle + * @param remainder The left over part of the original rectangle after slice + * @param amount The amount to cut off the rectangle starting from the right + * edge + * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise + * + * Use this function if we must cut a rectangle vertically. The @p amount + * parameter defines the inner x coordinate where to do the cut, starting from + * the right edge of the rectangle. If the @p amount value is greater than the + * rectangle width, there will be not cut possible and #EINA_FALSE will be + * returned. + */ +static inline Eina_Bool eina_rectangle_width_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); + +/** + * + * @brief Slices a rectangle horizontally starting from top edge + * + * @param thiz The rectangle to slice + * @param slice The sliced part of the rectangle + * @param remainder The left over part of the original rectangle after slice + * @param amount The amount to cut off the rectangle starting from the top edge + * @return #EINA_TRUE if the cut succeeds, #EINA_FALSE otherwise + * + * Use this function if we must cut a rectangle horizontally. The @p amount + * parameter defines the inner y coordinate where to do the cut, starting from + * the top edge of the rectangle. If the @p amount value is greater than the + * rectangle width, there will be not cut possible and #EINA_FALSE will be + * returned. + */ +static inline Eina_Bool eina_rectangle_height_cut(Eina_Rectangle *thiz, Eina_Rectangle *slice, Eina_Rectangle *remainder, int amount) EINA_ARG_NONNULL(1); + +/** + * @brief Subtract two rectangles. + * + * @param thiz The minuend rectangle + * @param other The subtrahend rectangle + * + * This function subtract two rectangles. The difference is stored on @p out + * There will be at most four differences, use eina_rectangle_is_valid to + * confirm the number of differences. + */ +static inline Eina_Bool eina_rectangle_subtract(Eina_Rectangle *thiz, Eina_Rectangle *other, Eina_Rectangle out[4]) EINA_ARG_NONNULL(1); /** * @brief Add a rectangle in a new pool. From 7dd6c353e2876dea810a32db4b7276a6947c7df5 Mon Sep 17 00:00:00 2001 From: Ghislain Loaec Date: Tue, 30 Sep 2014 16:32:47 +0200 Subject: [PATCH 12/55] eina: Eina_List API documentation --- src/lib/eina/eina_inline_list.x | 10 ---------- src/lib/eina/eina_list.h | 10 ++++++++++ 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/src/lib/eina/eina_inline_list.x b/src/lib/eina/eina_inline_list.x index 9faac2de2f..17830ba29f 100644 --- a/src/lib/eina/eina_inline_list.x +++ b/src/lib/eina/eina_inline_list.x @@ -64,16 +64,6 @@ eina_list_count(const Eina_List *list) return list->accounting->count; } - -/** - * @brief Returns the last list node's data - * - * @param list The list - * @return The node's data, or @c NULL on being passed a @c NULL pointer - * - * This macro is a shortcut for typing eina_list_data_get(eina_list_last()) - * @since 1.8 - */ static inline void * eina_list_last_data_get(const Eina_List *list) { diff --git a/src/lib/eina/eina_list.h b/src/lib/eina/eina_list.h index 7a720b076c..a32a1149ec 100644 --- a/src/lib/eina/eina_list.h +++ b/src/lib/eina/eina_list.h @@ -1267,6 +1267,16 @@ static inline void *eina_list_data_set(Eina_List *list, const void *data) */ static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE; +/** + * @brief Returns the last list node's data + * + * @param list The list + * @return The node's data, or @c NULL on being passed a @c NULL pointer + * + * This macro is a shortcut for typing eina_list_data_get(eina_list_last()) + * @since 1.8 + */ +static inline void *eina_list_last_data_get(const Eina_List *list) /** * @brief Returned a new iterator associated to a list. From 0001e36d397b8bd982949d410b6cbac3d6d1a9c2 Mon Sep 17 00:00:00 2001 From: Ghislain Loaec Date: Thu, 2 Oct 2014 10:25:26 +0200 Subject: [PATCH 13/55] eina: Eina_Fp API + Eina_Mempool TODOS --- src/lib/eina/eina_fp.h | 418 ++++++++++++++++++++++++++--- src/lib/eina/eina_inline_mempool.x | 46 ---- src/lib/eina/eina_mempool.h | 127 ++++++++- 3 files changed, 510 insertions(+), 81 deletions(-) diff --git a/src/lib/eina/eina_fp.h b/src/lib/eina/eina_fp.h index bc6c78d196..174cf0db73 100644 --- a/src/lib/eina/eina_fp.h +++ b/src/lib/eina/eina_fp.h @@ -20,6 +20,24 @@ #ifndef EINA_FP_H_ # define EINA_FP_H_ +/** + * @addtogroup Eina_Data_Types_Group Data Types + * + * @{ + */ + +/** + * @addtogroup Eina_Containers_Group Containers + * + * @{ + */ + +/** + * @defgroup Eina_Hash_Group Fp + * + * @{ + */ + #include "eina_types.h" #ifdef _MSC_VER @@ -32,81 +50,414 @@ typedef signed int int32_t; #define EINA_F32P32_PI 0x00000003243f6a89 + +/** + * @typedef Eina_F32p32 + * Type for floating point number where the size of the integer part is 32bits + * and the size of the decimal part is 32bits + */ typedef int64_t Eina_F32p32; + +/** + * @typedef Eina_F16p16 + * Type for floating point number where the size of the integer part is 16bits + * and the size of the decimal part is 16bits + */ typedef int32_t Eina_F16p16; + +/** + * @typedef Eina_F8p24 + * Type for floating point number where the size of the integer part is 8bits + * and the size of the decimal part is 24bits + */ typedef int32_t Eina_F8p24; +/** + * @brief Create a new Eina_F32p32 floating point number from standard 32 bits + * integer + * + * @param v 32bits integer value to convert + * @return The value converted into Eina_F32p32 format + */ static inline Eina_F32p32 eina_f32p32_int_from(int32_t v); + +/** + * @brief Create a new standard 32bits integer from Eina_F32p32 floating point + * number + * + * @param v Eina_F32p32 value to convert + * @return The value converted into 32bits integer + */ static inline int32_t eina_f32p32_int_to(Eina_F32p32 v); + +/** + * @brief Create a new Eina_F32p32 floating point number from standard double + * + * @param v double value to convert + * @return The value converted into Eina_F32p32 format + */ static inline Eina_F32p32 eina_f32p32_double_from(double v); + +/** + * @brief Create a new standard double from Eina_F32p32 floating point + * number + * + * @param v Eina_F32p32 value to convert + * @return The value converted into double + */ static inline double eina_f32p32_double_to(Eina_F32p32 v); -static inline Eina_F32p32 eina_f32p32_add(Eina_F32p32 a, - Eina_F32p32 b); -static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, - Eina_F32p32 b); -static inline Eina_F32p32 eina_f32p32_mul(Eina_F32p32 a, - Eina_F32p32 b); -static inline Eina_F32p32 eina_f32p32_scale(Eina_F32p32 a, - int b); -static inline Eina_F32p32 eina_f32p32_div(Eina_F32p32 a, - Eina_F32p32 b); +/** + * @brief Calculates the sum of two Eina_F32p32 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The sum result of the two numbers @p a + @p b + */ +static inline Eina_F32p32 eina_f32p32_add(Eina_F32p32 a, Eina_F32p32 b); + +/** + * @brief Calculates the substraction of two Eina_F32p32 floating point numbers + * + * @param a The first number + * @param b The substracted number + * @return The substaction result of the two numbers @p a - @p b + */ +static inline Eina_F32p32 eina_f32p32_sub(Eina_F32p32 a, Eina_F32p32 b); + +/** + * @brief Calculates the multiplication of two Eina_F32p32 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The mutliplication result of the two numbers @p a * @p b + * + * To prevent overflow during multiplication we need to reduce the precision of + * the fraction part Shift both values to only contain 16 bit of the fraction + * part (rounded). After multiplication we again have a value with a 32-bit + * fraction part. + */ +static inline Eina_F32p32 eina_f32p32_mul(Eina_F32p32 a, Eina_F32p32 b); + +/** + * @brief Calculates the scale multiplication of one Eina_F32p32 floating point + * number with an integer + * + * @param a The Eina_F32p32 number + * @param b The integer value + * @return The mutliplication result of the two numbers @p a * @p b + */ +static inline Eina_F32p32 eina_f32p32_scale(Eina_F32p32 a, int b); + +/** + * @brief Calculates the division of two Eina_F32p32 floating point numbers + * + * @param a The numerator number + * @param b The denominator number + * @return The division result of the two numbers @p a / @p b + */ +static inline Eina_F32p32 eina_f32p32_div(Eina_F32p32 a, Eina_F32p32 b); + +/** + * @brief Calculates the square root of an Eina_F32p32 floating point number + * + * @param a The number to calculate the square root from + * @return The square root result for the number @p a + */ static inline Eina_F32p32 eina_f32p32_sqrt(Eina_F32p32 a); + +/** + * @brief Get the absolute value of the integer part of and Eina_F32p32 floating + * point number + * + * @param a The floating point number + * @return The positive integer part of the number @p a + */ static inline unsigned int eina_f32p32_fracc_get(Eina_F32p32 v); // dont use llabs - issues if not on 64bit #define eina_fp32p32_llabs(a) ((a < 0) ? -(a) : (a)) +/** + * @brief Calculates the cosinus of a floating point number + * + * @param a The angle in radians to calculate the cosinus from. + * @return The cosinus value of the angle @p a + */ EAPI Eina_F32p32 eina_f32p32_cos(Eina_F32p32 a); + +/** + * @brief Calculates the sinus of a floating point number + * + * @param a The angle in radians to calculate the sinus from. + * @return The cosinus value of the angle @p a + */ EAPI Eina_F32p32 eina_f32p32_sin(Eina_F32p32 a); #define EINA_F16P16_ONE (1 << 16) #define EINA_F16P16_HALF (1 << 15) +/** + * @brief Create a new Eina_F16p316 floating point number from standard 32 bits + * integer + * + * @param v 32bits integer value to convert + * @return The value converted into Eina_F16p16 format + */ static inline Eina_F16p16 eina_f16p16_int_from(int32_t v); + +/** + * @brief Create a new standard 32bits integer from Eina_F16p16 floating point + * number + * + * @param v Eina_F16p16 value to convert + * @return The value converted into 32bits integer + */ static inline int32_t eina_f16p16_int_to(Eina_F16p16 v); + +/** + * @brief Create a new Eina_F16p16 floating point number from standard double + * + * @param v double value to convert + * @return The value converted into Eina_F16p16 format + */ static inline Eina_F16p16 eina_f16p16_double_from(double v); + +/** + * @brief Create a new standard double from Eina_F16p16 floating point + * number + * + * @param v Eina_F16p16 value to convert + * @return The value converted into double + */ static inline double eina_f16p16_double_to(Eina_F16p16 v); + +/** + * @brief Create a new Eina_F16p16 floating point number from standard float + * + * @param v float value to convert + * @return The value converted into Eina_F16p16 format + */ static inline Eina_F16p16 eina_f16p16_float_from(float v); + +/** + * @brief Create a new standard float from Eina_F16p16 floating point + * number + * + * @param v Eina_F16p16 value to convert + * @return The value converted into float + */ static inline float eina_f16p16_float_to(Eina_F16p16 v); -static inline Eina_F16p16 eina_f16p16_add(Eina_F16p16 a, - Eina_F16p16 b); -static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, - Eina_F16p16 b); -static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, - Eina_F16p16 b); -static inline Eina_F16p16 eina_f16p16_scale(Eina_F16p16 a, - int b); -static inline Eina_F16p16 eina_f16p16_div(Eina_F16p16 a, - Eina_F16p16 b); +/** + * @brief Calculates the sum of two Eina_F16p16 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The sum result of the two numbers @p a + @p b + */ +static inline Eina_F16p16 eina_f16p16_add(Eina_F16p16 a, Eina_F16p16 b); + +/** + * @brief Calculates the substraction of two Eina_F16p16 floating point numbers + * + * @param a The first number + * @param b The substracted number + * @return The substaction result of the two numbers @p a - @p b + */ +static inline Eina_F16p16 eina_f16p16_sub(Eina_F16p16 a, Eina_F16p16 b); + +/** + * @brief Calculates the multiplication of two Eina_F16p16 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The mutliplication result of the two numbers @p a * @p b + */ +static inline Eina_F16p16 eina_f16p16_mul(Eina_F16p16 a, Eina_F16p16 b); + +/** + * @brief Calculates the scale multiplication of one Eina_F16p16 floating point + * number with an integer + * + * @param a The Eina_F16p16 number + * @param b The integer value + * @return The mutliplication result of the two numbers @p a * @p b + */ +static inline Eina_F16p16 eina_f16p16_scale(Eina_F16p16 a, int b); + +/** + * @brief Calculates the division of two Eina_F16p16 floating point numbers + * + * @param a The numerator number + * @param b The denominator number + * @return The division result of the two numbers @p a / @p b + */ +static inline Eina_F16p16 eina_f16p16_div(Eina_F16p16 a, Eina_F16p16 b); + +/** + * @brief Calculates the square root of an Eina_F16p16 floating point number + * + * @param a The number to calculate the square root from + * @return The square root result for the number @p a + */ static inline Eina_F16p16 eina_f16p16_sqrt(Eina_F16p16 a); + +/** + * @brief Get the absolute value of the integer part of and Eina_F16p16 floating + * point number + * + * @param a The floating point number + * @return The positive integer part of the number @p a + */ static inline unsigned int eina_f16p16_fracc_get(Eina_F16p16 v); + +/** + * @brief Create a new Eina_F16p316 floating point number from standard 32 bits + * integer + * + * @param v 32bits integer value to convert + * @return The value converted into Eina_F8p24 format + */ static inline Eina_F8p24 eina_f8p24_int_from(int32_t v); + +/** + * @brief Create a new standard 32bits integer from Eina_F8p24 floating point + * number + * + * @param v Eina_F8p24 value to convert + * @return The value converted into 32bits integer + */ static inline int32_t eina_f8p24_int_to(Eina_F8p24 v); + +/** + * @brief Create a new Eina_F8p24 floating point number from standard float + * + * @param v float value to convert + * @return The value converted into Eina_F8p24 format + */ static inline Eina_F8p24 eina_f8p24_float_from(float v); + +/** + * @brief Create a new standard float from Eina_F8p24 floating point + * number + * + * @param v Eina_F8p24 value to convert + * @return The value converted into float + */ static inline float eina_f8p24_float_to(Eina_F8p24 v); -static inline Eina_F8p24 eina_f8p24_add(Eina_F8p24 a, - Eina_F8p24 b); -static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, - Eina_F8p24 b); -static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, - Eina_F8p24 b); -static inline Eina_F8p24 eina_f8p24_scale(Eina_F8p24 a, - int b); -static inline Eina_F8p24 eina_f8p24_div(Eina_F8p24 a, - Eina_F8p24 b); +/** + * @brief Calculates the sum of two Eina_F8p24 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The sum result of the two numbers @p a + @p b + */ +static inline Eina_F8p24 eina_f8p24_add(Eina_F8p24 a, Eina_F8p24 b); + +/** + * @brief Calculates the substraction of two Eina_F8p24 floating point numbers + * + * @param a The first number + * @param b The substracted number + * @return The substaction result of the two numbers @p a - @p b + */ +static inline Eina_F8p24 eina_f8p24_sub(Eina_F8p24 a, Eina_F8p24 b); + +/** + * @brief Calculates the multiplication of two Eina_F8p24 floating point numbers + * + * @param a The first number + * @param b The second number + * @return The mutliplication result of the two numbers @p a * @p b + */ +static inline Eina_F8p24 eina_f8p24_mul(Eina_F8p24 a, Eina_F8p24 b); + +/** + * @brief Calculates the scale multiplication of one Eina_F8p24 floating point + * number with an integer + * + * @param a The Eina_F16p16 number + * @param b The integer value + * @return The mutliplication result of the two numbers @p a * @p b + */ +static inline Eina_F8p24 eina_f8p24_scale(Eina_F8p24 a, int b); + +/** + * @brief Calculates the division of two Eina_F8p24 floating point numbers + * + * @param a The numerator number + * @param b The denominator number + * @return The division result of the two numbers @p a / @p b + */ +static inline Eina_F8p24 eina_f8p24_div(Eina_F8p24 a, Eina_F8p24 b); + +/** + * @brief Calculates the square root of an Eina_F8p24 floating point number + * + * @param a The number to calculate the square root from + * @return The square root result for the number @p a + */ static inline Eina_F8p24 eina_f8p24_sqrt(Eina_F8p24 a); + +/** + * @brief Get the absolute value of the integer part of and Eina_F8p24 floating + * point number + * + * @param a The floating point number + * @return The positive integer part of the number @p a + */ static inline unsigned int eina_f8p24_fracc_get(Eina_F8p24 v); +/** + * @brief Converts an Eina_F16p16 floating point number into Eina_F32p32 format + * + * @param a The Eina_F16p16 floating point number + * @return The converted Eina_F32p32 floating point number + */ static inline Eina_F32p32 eina_f16p16_to_f32p32(Eina_F16p16 a); + +/** + * @brief Converts an Eina_F8p24 floating point number into Eina_F32p32 format + * + * @param a The Eina_F8p24 floating point number + * @return The converted Eina_F32p32 floating point number + */ static inline Eina_F32p32 eina_f8p24_to_f32p32(Eina_F8p24 a); + +/** + * @brief Converts an Eina_F32p32 floating point number into Eina_F16p16 format + * + * @param a The Eina_F32p32 floating point number + * @return The converted Eina_F16p16 floating point number + */ static inline Eina_F16p16 eina_f32p32_to_f16p16(Eina_F32p32 a); + +/** + * @brief Converts an Eina_F8p24 floating point number into Eina_F16p16 format + * + * @param a The Eina_F8p24 floating point number + * @return The converted Eina_F16p16 floating point number + */ static inline Eina_F16p16 eina_f8p24_to_f16p16(Eina_F8p24 a); + +/** + * @brief Converts an Eina_F32p32 floating point number into Eina_F8p24 format + * + * @param a The Eina_F32p32 floating point number + * @return The converted Eina_F8p16 floating point number + */ static inline Eina_F8p24 eina_f32p32_to_f8p24(Eina_F32p32 a); + +/** + * @brief Converts an Eina_F16p16 floating point number into Eina_F8p16 format + * + * @param a The Eina_F16p16 floating point number + * @return The converted Eina_F8p16 floating point number + */ static inline Eina_F8p24 eina_f16p16_to_f8p24(Eina_F16p16 a); #include "eina_inline_f32p32.x" @@ -114,4 +465,11 @@ static inline Eina_F8p24 eina_f16p16_to_f8p24(Eina_F16p16 a); #include "eina_inline_f8p24.x" #include "eina_inline_fp.x" +/** + * @} + */ + +/** + * @} + */ #endif diff --git a/src/lib/eina/eina_inline_mempool.x b/src/lib/eina/eina_inline_mempool.x index fc3dd00add..032ce06d81 100644 --- a/src/lib/eina/eina_inline_mempool.x +++ b/src/lib/eina/eina_inline_mempool.x @@ -68,53 +68,18 @@ struct _Eina_Mempool Eina_Mempool_Backend_ABI2 *backend2; }; -/** - * @brief Re-allocate an amount memory by the given mempool. - * - * @param mp The mempool. - * @param element The element to re-allocate. - * @param size The size in bytes to re-allocate. - * @return The newly re-allocated data. - * - * This function re-allocates and returns @p element with @p size bytes using the - * mempool @p mp. If not used anymore, the data must be freed with eina_mempool_free(). - * @warning No checks are done for @p mp. - */ static inline void * eina_mempool_realloc(Eina_Mempool *mp, void *element, unsigned int size) { return mp->backend.realloc(mp->backend_data, element, size); } -/** - * @brief Allocate memory using the given mempool. - * - * @param mp The mempool. - * @param size The size in bytes to allocate. - * @return The newly allocated data. - * - * This function allocates and returns @p size bytes using the mempool @p mp. - * If not used anymore, the data must be freed with eina_mempool_free(). - * @warning No checks are done for @p mp. - */ static inline void * eina_mempool_malloc(Eina_Mempool *mp, unsigned int size) { return mp->backend.alloc(mp->backend_data, size); } -/** - * @brief Allocate and zero memory using the given mempool. - * - * @param mp The mempool. - * @param size The size in bytes to allocate. - * @return The newly allocated data. - * - * This function allocates, zeroes, and returns @p size bytes using the mempool @p mp. - * If not used anymore, the data must be freed with eina_mempool_free(). - * @warning No checks are done for @p mp. - * @since 1.2 - */ static inline void * eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) { @@ -124,17 +89,6 @@ eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) return r; } -/** - * @brief Free resources previously allocated by the given mempool. - * - * @param mp The mempool. - * @param element The data to free. - * - * This function frees @p element allocated by @p mp. @p element must - * have been obtained from eina_mempool_malloc(), eina_mempool_calloc(), or - * eina_mempool_realloc(). - * @warning No checks are done for @p mp. - */ static inline void eina_mempool_free(Eina_Mempool *mp, void *element) { diff --git a/src/lib/eina/eina_mempool.h b/src/lib/eina/eina_mempool.h index 2dd4787972..9e1d97fcc1 100644 --- a/src/lib/eina/eina_mempool.h +++ b/src/lib/eina/eina_mempool.h @@ -39,8 +39,8 @@ * @li @c pass_through: it just call malloc() and free(). It may be * faster on some computers than using our own allocators (like having * a huge L2 cache, over 4MB). - * @li @c one_big: It call just one time malloc for the requested number - * of items. Useful when you know in advance how many object of some + * @li @c one_big: It calls just one time malloc for the requested number + * of items. Useful when you know in advance how many objects of some * type will live during the life of the mempool. */ @@ -78,22 +78,139 @@ typedef void (*Eina_Mempool_Repack_Cb)(void *dst, void *src, void *data); EAPI extern Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE; +/** + * + * @brief TODO + * + * @param module + * @param context + * @param options + * @return Newly allocated mempool instance, NULL otherwise. + * + */ EAPI Eina_Mempool *eina_mempool_add(const char *module, const char *context, const char *options, ...) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); + +/** + * + * @brief TODO + * + * @param mp The mempools + * + */ EAPI void eina_mempool_del(Eina_Mempool *mp) EINA_ARG_NONNULL(1); +/** + * @brief Re-allocate an amount memory by the given mempool. + * + * @param mp The mempool. + * @param element The element to re-allocate. + * @param size The size in bytes to re-allocate. + * @return The newly re-allocated data. + * + * This function re-allocates and returns @p element with @p size bytes using the + * mempool @p mp. If not used anymore, the data must be freed with eina_mempool_free(). + * @warning No checks are done for @p mp. + */ static inline void *eina_mempool_realloc(Eina_Mempool *mp, void *element, unsigned int size) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Allocate memory using the given mempool. + * + * @param mp The mempool. + * @param size The size in bytes to allocate. + * @return The newly allocated data. + * + * This function allocates and returns @p size bytes using the mempool @p mp. + * If not used anymore, the data must be freed with eina_mempool_free(). + * @warning No checks are done for @p mp. + */ static inline void *eina_mempool_malloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Allocate and zero memory using the given mempool. + * + * @param mp The mempool. + * @param size The size in bytes to allocate. + * @return The newly allocated data. + * + * This function allocates, zeroes, and returns @p size bytes using the mempool @p mp. + * If not used anymore, the data must be freed with eina_mempool_free(). + * @warning No checks are done for @p mp. + * @since 1.2 + */ +static inline void *eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) EINA_MALLOC EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Free resources previously allocated by the given mempool. + * + * @param mp The mempool. + * @param element The data to free. + * + * This function frees @p element allocated by @p mp. @p element must + * have been obtained from eina_mempool_malloc(), eina_mempool_calloc(), or + * eina_mempool_realloc(). + * @warning No checks are done for @p mp. + */ static inline void eina_mempool_free(Eina_Mempool *mp, void *element) EINA_ARG_NONNULL(1); -EAPI void eina_mempool_repack(Eina_Mempool *mp, - Eina_Mempool_Repack_Cb cb, - void *data) EINA_ARG_NONNULL(1, 2); +/** + * + * @brief TODO + * + * @param mp The mempool + * @param cb The after repack callback + * @param data The data + * + */ +EAPI void eina_mempool_repack(Eina_Mempool *mp, Eina_Mempool_Repack_Cb cb, void *data) EINA_ARG_NONNULL(1, 2); + +/** + * + * @brief TODO (garbage collect) + * + * @param mp The mempool + * + */ EAPI void eina_mempool_gc(Eina_Mempool *mp) EINA_ARG_NONNULL(1); + +/** + * + * @brief TODO + * + * @param mp The mempool + * + */ EAPI void eina_mempool_statistics(Eina_Mempool *mp) EINA_ARG_NONNULL(1); +/** + * + * @brief TODO + * + * @param be The backend + * @return #EINA_TRUE if backend has been correctly registered, #EINA_FALSE + * otherwise. + * + */ EAPI Eina_Bool eina_mempool_register(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1); + +/** + * + * @brief TODO + * + * @param be The backend + * + */ EAPI void eina_mempool_unregister(Eina_Mempool_Backend *be) EINA_ARG_NONNULL(1); +/** + * + * @brief TODO + * + * @param size + * @return #EINA_TRUE if backend has been correctly registered, #EINA_FALSE + * otherwise. + * + */ static inline unsigned int eina_mempool_alignof(unsigned int size); #include "eina_inline_mempool.x" From 604d3ae8a27d4f6661d0606b115e3cf0459c1715 Mon Sep 17 00:00:00 2001 From: Ghislain Loaec Date: Fri, 3 Oct 2014 11:36:38 +0200 Subject: [PATCH 14/55] eina: Eina_Cpu / Eina_Thread API documentation --- src/lib/eina/Eina.h | 2 + src/lib/eina/eina_cpu.h | 84 ++++++++++++++++++++++++++++++++++++++ src/lib/eina/eina_fp.h | 77 +++++++++++++++++++++------------- src/lib/eina/eina_list.h | 2 +- src/lib/eina/eina_thread.h | 12 ++++++ 5 files changed, 148 insertions(+), 29 deletions(-) diff --git a/src/lib/eina/Eina.h b/src/lib/eina/Eina.h index 9a8341d527..bb6d32555b 100644 --- a/src/lib/eina/Eina.h +++ b/src/lib/eina/Eina.h @@ -66,6 +66,7 @@ * Linux, BSD, Opensolaris and Windows (XP and CE). * * The data types that are available are (see @ref Eina_Data_Types_Group): + * @li @ref Eina_Fp_Group standard floating point numbers. * @li @ref Eina_Inline_Array_Group standard array of inlined members. * @li @ref Eina_Array_Group standard array of @c void* data. * @li @ref Eina_Hash_Group standard hash of @c void* data. @@ -86,6 +87,7 @@ * @li @ref Eina_Benchmark_Group helper to write benchmarks. * @li @ref Eina_Convert_Group faster conversion from strings to integers, double, etc. * @li @ref Eina_Counter_Group measures number of calls and their time. + * @li @ref Eina_Cpu_Group Cpu and architecture related helpers. * @li @ref Eina_Error_Group error identifiers. * @li @ref Eina_File_Group simple file list and path split. * @li @ref Eina_Lalloc_Group simple lazy allocator. diff --git a/src/lib/eina/eina_cpu.h b/src/lib/eina/eina_cpu.h index e31ed76735..e871774aa2 100644 --- a/src/lib/eina/eina_cpu.h +++ b/src/lib/eina/eina_cpu.h @@ -19,8 +19,30 @@ #ifndef EINA_CPU_H_ #define EINA_CPU_H_ +/** + * @addtogroup Eina_Cpu_Group Cpu + * + * @brief Cpu and architecture related helpers + */ + +/** + * @addtogroup Eina_Tools_Group Tools + * + * @{ + */ + +/** + * @defgroup Eina_Cpu_Group Cpu + * + * @{ + */ + #include "eina_types.h" +/** + * @typedef Eina_Cpu_Features + * Enumerates different hardware architectures. + */ typedef enum _Eina_Cpu_Features { EINA_CPU_MMX = 0x00000001, @@ -36,16 +58,78 @@ typedef enum _Eina_Cpu_Features EINA_CPU_SSE42 = 0x00000200 } Eina_Cpu_Features; +/** + * @brief Global hardware architecture handler + * + * @return the current cpu features + */ EAPI extern Eina_Cpu_Features eina_cpu_features; +/** + * @brief Cpu features accessor + * + * @return the current cpu features + */ EAPI Eina_Cpu_Features eina_cpu_features_get(void); + +/** + * @brief Get the current number of precessors + * + * @return the number of processors that are online, that + * is available when the function is called. + */ EAPI int eina_cpu_count(void); + +/** + * @brief Get the current virtual page size + * + * @return the fixed length that represents the smallest unit of data for memory + * allocation performed by the operating system on behalf of the program, and + * for transfers between the main memory and any other auxiliary store. + */ EAPI int eina_cpu_page_size(void); +/** + * @brief Reverses the byte order of a 16-bit (destination) register. + * + * @param x The binary word to swap + * @return a byte order swapped 16-bit integer. + * + * On big endian systems, the number is converted to little endian byte order. + * On little endian systems, the number is converted to big endian byte order. + */ static inline unsigned short eina_swap16(unsigned short x); + +/** + * @brief Reverses the byte order of a 32-bit (destination) register. + * + * @param x The binary word to swap + * @return a byte order swapped 32-bit integer. + * + * On big endian systems, the number is converted to little endian byte order. + * On little endian systems, the number is converted to big endian byte order. + */ static inline unsigned int eina_swap32(unsigned int x); + +/** + * @brief Reverses the byte order of a 64-bit (destination) register. + * + * @param x The binary word to swap + * @return a byte order swapped 64-bit integer. + * + * On big endian systems, the number is converted to little endian byte order. + * On little endian systems, the number is converted to big endian byte order. + */ static inline unsigned long long eina_swap64(unsigned long long x); #include "eina_inline_cpu.x" +/** + * @} + */ + +/** + * @} + */ + #endif /* EINA_CPU_H_ */ diff --git a/src/lib/eina/eina_fp.h b/src/lib/eina/eina_fp.h index 174cf0db73..7a169a20f5 100644 --- a/src/lib/eina/eina_fp.h +++ b/src/lib/eina/eina_fp.h @@ -20,6 +20,12 @@ #ifndef EINA_FP_H_ # define EINA_FP_H_ +/** + * @addtogroup Eina_Fp_Group Fp + * + * @brief Floating point numbers data type management. + */ + /** * @addtogroup Eina_Data_Types_Group Data Types * @@ -27,13 +33,7 @@ */ /** - * @addtogroup Eina_Containers_Group Containers - * - * @{ - */ - -/** - * @defgroup Eina_Hash_Group Fp + * @defgroup Eina_Fp_Group Fp * * @{ */ @@ -48,45 +48,48 @@ typedef signed int int32_t; # include #endif +/** + * @def EINA_F32P32_PI + * @brief Yields the 32-bit PI constant + */ #define EINA_F32P32_PI 0x00000003243f6a89 - /** * @typedef Eina_F32p32 - * Type for floating point number where the size of the integer part is 32bits - * and the size of the decimal part is 32bits + * Type for floating point number where the size of the integer part is 32-bit + * and the size of the decimal part is 32-bit */ typedef int64_t Eina_F32p32; /** * @typedef Eina_F16p16 - * Type for floating point number where the size of the integer part is 16bits - * and the size of the decimal part is 16bits + * Type for floating point number where the size of the integer part is 16-bit + * and the size of the decimal part is 16-bit */ typedef int32_t Eina_F16p16; /** * @typedef Eina_F8p24 - * Type for floating point number where the size of the integer part is 8bits + * Type for floating point number where the size of the integer part is 8-bit * and the size of the decimal part is 24bits */ typedef int32_t Eina_F8p24; /** - * @brief Create a new Eina_F32p32 floating point number from standard 32 bits + * @brief Create a new Eina_F32p32 floating point number from standard 32-bit * integer * - * @param v 32bits integer value to convert + * @param v 32-bit integer value to convert * @return The value converted into Eina_F32p32 format */ static inline Eina_F32p32 eina_f32p32_int_from(int32_t v); /** - * @brief Create a new standard 32bits integer from Eina_F32p32 floating point + * @brief Create a new standard 32-bit integer from Eina_F32p32 floating point * number * * @param v Eina_F32p32 value to convert - * @return The value converted into 32bits integer + * @return The value converted into 32-bit integer */ static inline int32_t eina_f32p32_int_to(Eina_F32p32 v); @@ -175,7 +178,14 @@ static inline Eina_F32p32 eina_f32p32_sqrt(Eina_F32p32 a); */ static inline unsigned int eina_f32p32_fracc_get(Eina_F32p32 v); -// dont use llabs - issues if not on 64bit +/** + * @brief Get the absolute value of an Eina_F32p32 floating point number + * + * @param a The floating point number + * @return The absolute value for the number @p a + * @warning Has known issues on 64-bit architecture, prefer + * eina_f32p32_fracc_get() instead + */ #define eina_fp32p32_llabs(a) ((a < 0) ? -(a) : (a)) /** @@ -195,24 +205,35 @@ EAPI Eina_F32p32 eina_f32p32_cos(Eina_F32p32 a); EAPI Eina_F32p32 eina_f32p32_sin(Eina_F32p32 a); +/** + * @def EINA_F16P16_ONE + * + * Yields the maximum 16-bit unsigned integer size (= 65536) + */ #define EINA_F16P16_ONE (1 << 16) + +/** + * @def EINA_F16P16_HALF + * + * Yields the maximum 16-bit signed integer size (= 32768) + */ #define EINA_F16P16_HALF (1 << 15) /** - * @brief Create a new Eina_F16p316 floating point number from standard 32 bits + * @brief Create a new Eina_F16p316 floating point number from standard 32-bit * integer * - * @param v 32bits integer value to convert + * @param v 32-bit integer value to convert * @return The value converted into Eina_F16p16 format */ static inline Eina_F16p16 eina_f16p16_int_from(int32_t v); /** - * @brief Create a new standard 32bits integer from Eina_F16p16 floating point + * @brief Create a new standard 32-bit integer from Eina_F16p16 floating point * number * * @param v Eina_F16p16 value to convert - * @return The value converted into 32bits integer + * @return The value converted into 32-bit integer */ static inline int32_t eina_f16p16_int_to(Eina_F16p16 v); @@ -315,20 +336,20 @@ static inline unsigned int eina_f16p16_fracc_get(Eina_F16p16 v); /** - * @brief Create a new Eina_F16p316 floating point number from standard 32 bits + * @brief Create a new Eina_F16p316 floating point number from standard 32-bit * integer * - * @param v 32bits integer value to convert + * @param v 32-bit integer value to convert * @return The value converted into Eina_F8p24 format */ static inline Eina_F8p24 eina_f8p24_int_from(int32_t v); /** - * @brief Create a new standard 32bits integer from Eina_F8p24 floating point + * @brief Create a new standard 32-bit integer from Eina_F8p24 floating point * number * * @param v Eina_F8p24 value to convert - * @return The value converted into 32bits integer + * @return The value converted into 32-bit integer */ static inline int32_t eina_f8p24_int_to(Eina_F8p24 v); @@ -341,8 +362,7 @@ static inline int32_t eina_f8p24_int_to(Eina_F8p24 v); static inline Eina_F8p24 eina_f8p24_float_from(float v); /** - * @brief Create a new standard float from Eina_F8p24 floating point - * number + * @brief Create a new standard float from Eina_F8p24 floating point number * * @param v Eina_F8p24 value to convert * @return The value converted into float @@ -472,4 +492,5 @@ static inline Eina_F8p24 eina_f16p16_to_f8p24(Eina_F16p16 a); /** * @} */ + #endif diff --git a/src/lib/eina/eina_list.h b/src/lib/eina/eina_list.h index a32a1149ec..91de6ea08c 100644 --- a/src/lib/eina/eina_list.h +++ b/src/lib/eina/eina_list.h @@ -1276,7 +1276,7 @@ static inline unsigned int eina_list_count(const Eina_List *list) EINA_PURE; * This macro is a shortcut for typing eina_list_data_get(eina_list_last()) * @since 1.8 */ -static inline void *eina_list_last_data_get(const Eina_List *list) +static inline void *eina_list_last_data_get(const Eina_List *list); /** * @brief Returned a new iterator associated to a list. diff --git a/src/lib/eina/eina_thread.h b/src/lib/eina/eina_thread.h index 3e89ea9f24..3ad5486ddd 100644 --- a/src/lib/eina/eina_thread.h +++ b/src/lib/eina/eina_thread.h @@ -42,10 +42,22 @@ * @{ */ +/** + * @typedef Eina_Thread + * Type for a generic thread. + */ typedef unsigned long int Eina_Thread; +/** + * @typedef Eina_Thread_Cb + * Type for the definition of a thread callback function + */ typedef void *(*Eina_Thread_Cb)(void *data, Eina_Thread t); +/** + * @typedef Eina_Thead_Priority + * Type to enumerate different thread priorities + */ typedef enum _Eina_Thread_Priority { EINA_THREAD_URGENT, From 0f6e45e2a04bdc4a6c040fa41b28339ab807aae8 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Tue, 14 Oct 2014 11:21:55 +0200 Subject: [PATCH 15/55] evas: add documentation on missing types and return values of Evas_Common.h. --- src/lib/evas/Evas_Common.h | 30 ++++++++++++++++++------------ 1 file changed, 18 insertions(+), 12 deletions(-) diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h index 6dfa5113cf..c1f78f889c 100644 --- a/src/lib/evas/Evas_Common.h +++ b/src/lib/evas/Evas_Common.h @@ -318,7 +318,7 @@ typedef struct _Evas_Video_Surface Evas_Video_Surface; typedef unsigned long long Evas_Modifier_Mask; /**< An Evas modifier mask type */ -typedef int Evas_Coord; +typedef int Evas_Coord /**< A type for coordinates */; typedef int Evas_Font_Size; typedef int Evas_Angle; @@ -336,12 +336,13 @@ struct _Evas_Coord_Point Evas_Coord y; /**< y co-ordinate */ }; -struct _Evas_Coord_Size +struct _Evas_Coord_Size /**< A size in Evas_Coord */ { Evas_Coord w; /**< width */ Evas_Coord h; /**< height */ }; + struct _Evas_Coord_Precision_Size { Evas_Coord w; /** < width */ @@ -352,25 +353,28 @@ struct _Evas_Coord_Precision_Size struct _Evas_Coord_Precision_Point { - Evas_Coord x, y; - double xsub, ysub; + Evas_Coord x; /**< x co-ordinate */ + Evas_Coord y; /**< y co-ordinate */ + double xsub; /** < subpixel precision for x */ + double ysub; /** < subpixel precision for y */ }; struct _Evas_Point { - int x, y; + int x; /**< x co-ordinate */ + int y; /**< y co-ordinate */ }; struct _Evas_Position { - Evas_Point output; + Evas_Point output; /**< position on the output */ Evas_Coord_Point canvas; /**< position on the canvas */ }; struct _Evas_Precision_Position { - Evas_Point output; - Evas_Coord_Precision_Point canvas; + Evas_Point output; /**< position on the output */ + Evas_Coord_Precision_Point canvas; /**< position on the canvas */ }; typedef enum _Evas_Aspect_Control @@ -505,7 +509,7 @@ typedef void (*Evas_Video_Coord_Cb)(void *data, Evas_Object *obj, const Evas_Vid struct _Evas_Video_Surface { - int version; + int version; /**< The Evas Video surface version in use @see EVAS_VIDEO_SURFACE_VERSION*/ Evas_Video_Coord_Cb move; /**< Move the video surface to this position */ Evas_Video_Coord_Cb resize; /**< Resize the video surface to that size */ @@ -513,7 +517,7 @@ struct _Evas_Video_Surface Evas_Video_Cb hide; /**< Hide the video overlay surface */ Evas_Video_Cb update_pixels; /**< Please update the Evas_Object_Image pixels when called */ - Evas_Object *parent; + Evas_Object *parent; /**< The parent object */ void *data; }; @@ -571,8 +575,8 @@ typedef enum _Evas_Border_Fill_Mode typedef enum _Evas_Engine_Render_Mode { - EVAS_RENDER_MODE_BLOCKING = 0, - EVAS_RENDER_MODE_NONBLOCKING = 1, + EVAS_RENDER_MODE_BLOCKING = 0, /**< The rendering is blocking mode*/ + EVAS_RENDER_MODE_NONBLOCKING = 1, /** < The rendering is non blocking mode*/ } Evas_Engine_Render_Mode; typedef enum _Evas_Image_Content_Hint @@ -1337,6 +1341,8 @@ EAPI Evas_Device *evas_device_add(Evas *e); /** * Delete a new device type * + * @param dev The device node you want to delete. + * * @see evas_device_add * @see evas_device_push * @see evas_device_pop From 8b582dc0f5fb8da301061ac3dd972fb835356385 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Thu, 16 Oct 2014 11:19:15 +0200 Subject: [PATCH 16/55] evas: add more documentation in Evas_Common.h. --- src/lib/evas/Evas_Common.h | 48 ++++++++++++++++++++++++++++++++------ 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h index c1f78f889c..95f788652e 100644 --- a/src/lib/evas/Evas_Common.h +++ b/src/lib/evas/Evas_Common.h @@ -1037,6 +1037,8 @@ EAPI int evas_async_events_process(void); * @param event_info Information about the event. * @param func The callback function pointer. * + * @return EINA_FALSE if an error occured, EINA_TRUE otherwise. + * * This is the way, for a routine running outside evas' main thread, * to report an asynchronous event. A callback function is informed, * whose call is to happen after evas_async_events_process() is @@ -2333,6 +2335,7 @@ EAPI void evas_map_alpha_set(Evas_Map *m, Eina_Bool enabled); * This gets the alpha flag for map rendering. * * @param m map to get the alpha from. Must not be NULL. + * @return EINA_FALSE if map is NULL EINA_TRUE otherwise. */ EAPI Eina_Bool evas_map_alpha_get(const Evas_Map *m); @@ -2915,7 +2918,14 @@ typedef void (*Evas_Object_Intercept_Clip_Unset_Cb)(void *data, Evas_Object *obj * @{ */ - +/** + * Function signature for the evas object pixels get callback function + * @see evas_object_image_pixels_get() + * + * By @a data it will be passed the private data. By @a o it will be passed the + * Evas_Object image on which the pixels are requested. + * + */ typedef void (*Evas_Object_Image_Pixels_Get_Cb)(void *data, Evas_Object *o); /** @@ -3141,31 +3151,55 @@ typedef enum _Evas_Text_Style_Type * @{ */ +/** + * @typedef Evas_Textblock_Style + * + * A textblock style object. + * @see evas_textblock_style_new() + * @see evas_textblock_style_get() + * @see evas_textblock_style_set() + */ + typedef struct _Evas_Textblock_Style Evas_Textblock_Style; + +/** + * @typedef Evas_Textblock_Cursor + * + * A textblock cursor object, used to maipulate the cursor of an evas textblock + * @see evas_object_textblock_cursor_new + * + */ typedef struct _Evas_Textblock_Cursor Evas_Textblock_Cursor; + /** * @typedef Evas_Object_Textblock_Node_Format * A format node. */ typedef struct _Evas_Object_Textblock_Node_Format Evas_Object_Textblock_Node_Format; -typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle; +typedef struct _Evas_Textblock_Rectangle Evas_Textblock_Rectangle; struct _Evas_Textblock_Rectangle { Evas_Coord x, y, w, h; }; +/** + * Text type for evas textblock. + */ typedef enum _Evas_Textblock_Text_Type { - EVAS_TEXTBLOCK_TEXT_RAW, - EVAS_TEXTBLOCK_TEXT_PLAIN, - EVAS_TEXTBLOCK_TEXT_MARKUP + EVAS_TEXTBLOCK_TEXT_RAW, /**< textblock text of type raw */ + EVAS_TEXTBLOCK_TEXT_PLAIN, /**< textblock text of type plain */ + EVAS_TEXTBLOCK_TEXT_MARKUP /**< textblock text of type markup */ } Evas_Textblock_Text_Type; +/** + * Cursor type for evas textblock. + */ typedef enum _Evas_Textblock_Cursor_Type { - EVAS_TEXTBLOCK_CURSOR_UNDER, - EVAS_TEXTBLOCK_CURSOR_BEFORE + EVAS_TEXTBLOCK_CURSOR_UNDER, /**< cursor type is under */ + EVAS_TEXTBLOCK_CURSOR_BEFORE /**< cursor type is before */ } Evas_Textblock_Cursor_Type; /** From f59359d5bec3257df3cbee0f57f231c93e567954 Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Fri, 10 Oct 2014 17:12:40 +0200 Subject: [PATCH 17/55] ecore: update missing Ecore_Common.h API documentation. Add some new documentation when missing, and fix old documentation warnings in Doxygen output. --- src/lib/ecore/Ecore_Common.h | 92 +++++++++++++++++++++++++++++------- 1 file changed, 75 insertions(+), 17 deletions(-) diff --git a/src/lib/ecore/Ecore_Common.h b/src/lib/ecore/Ecore_Common.h index 8ed1742a58..f47ab39997 100644 --- a/src/lib/ecore/Ecore_Common.h +++ b/src/lib/ecore/Ecore_Common.h @@ -67,8 +67,8 @@ EAPI int ecore_shutdown(void); * @{ */ -#define ECORE_VERSION_MAJOR EFL_VERSION_MAJOR -#define ECORE_VERSION_MINOR EFL_VERSION_MINOR +#define ECORE_VERSION_MAJOR EFL_VERSION_MAJOR /**< Ecore version major number */ +#define ECORE_VERSION_MINOR EFL_VERSION_MINOR /**< Ecore version minor number */ /** * @typedef Ecore_Version @@ -149,6 +149,7 @@ EAPI void ecore_main_loop_iterate(void); * DO NOT use this function unless you are the person God comes to ask for * advice when He has trouble managing the Universe. * + * @return 1 if event exists, else 0. * @see ecore_main_loop_iterate() */ EAPI int ecore_main_loop_iterate_may_block(int may_block); @@ -295,10 +296,14 @@ typedef void *(*Ecore_Data_Cb)(void *data); /** * Add a function to be called by ecore_fork_reset() * + * @param func The function to add. + * @param data The data to pass to this function. + * * This queues @p func to be called (and passed @p data as its argument) when * ecore_fork_reset() is called. This allows other libraries and subsystems * to also reset their internal state after a fork. * + * @return EINA_TRUE on success, else EINA_FALSE. * @since 1.7 */ EAPI Eina_Bool ecore_fork_reset_callback_add(Ecore_Cb func, const void *data); @@ -306,9 +311,13 @@ EAPI Eina_Bool ecore_fork_reset_callback_add(Ecore_Cb func, const void *data); /** * This removes the callback specified * + * @param func The function to delete. + * @param data The data passed to this function. + * * This deletes the callback added by ecore_fork_reset_callback_add() using * the function and data pointer to specify which to remove. * + * @return EINA_TRUE on success, else EINA_FALSE. * @since 1.7 */ EAPI Eina_Bool ecore_fork_reset_callback_del(Ecore_Cb func, const void *data); @@ -472,7 +481,7 @@ EAPI int ecore_thread_main_loop_end(void); * @{ */ -#define ECORE_EVENT_NONE 0 +#define ECORE_EVENT_NONE 0 /**< None event */ #define ECORE_EVENT_SIGNAL_USER 1 /**< User signal event */ #define ECORE_EVENT_SIGNAL_HUP 2 /**< Hup signal event */ #define ECORE_EVENT_SIGNAL_EXIT 3 /**< Exit signal event */ @@ -483,7 +492,7 @@ EAPI int ecore_thread_main_loop_end(void); #define ECORE_EVENT_LOCALE_CHANGED 8 /**< Locale changed */ #define ECORE_EVENT_HOSTNAME_CHANGED 9 /**< Hostname changed */ #define ECORE_EVENT_SYSTEM_TIMEDATE_CHANGED 10 /**< Time or Date changed */ -#define ECORE_EVENT_COUNT 11 +#define ECORE_EVENT_COUNT 11 /**< Number of events */ typedef struct _Ecore_Win32_Handler Ecore_Win32_Handler; /**< A handle for HANDLE handlers on Windows */ typedef struct _Ecore_Event_Handler Ecore_Event_Handler; /**< A handle for an event handler */ @@ -515,7 +524,11 @@ typedef void (*Ecore_End_Cb)(void *user_data, void *func_data); */ typedef Eina_Bool (*Ecore_Event_Handler_Cb)(void *data, int type, void *event); -struct _Ecore_Event_Signal_User /** User signal event */ +/** + * @struct _Ecore_Event_Signal_User + * @brief A structure that stores information of a User signal event. + */ +struct _Ecore_Event_Signal_User { int number; /**< The signal number. Either 1 or 2 */ void *ext_data; /**< Extension data - not used */ @@ -525,7 +538,11 @@ struct _Ecore_Event_Signal_User /** User signal event */ #endif }; -struct _Ecore_Event_Signal_Hup /** Hup signal event */ +/** + * @struct _Ecore_Event_Signal_Hup + * @brief A structure that stores information of a Hup signal event. + */ +struct _Ecore_Event_Signal_Hup { void *ext_data; /**< Extension data - not used */ @@ -534,7 +551,11 @@ struct _Ecore_Event_Signal_Hup /** Hup signal event */ #endif }; -struct _Ecore_Event_Signal_Exit /** Exit request event */ +/** + * @struct _Ecore_Event_Signal_Exit + * @brief A structure that stores information of an Exit request event. + */ +struct _Ecore_Event_Signal_Exit { Eina_Bool interrupt : 1; /**< Set if the exit request was an interrupt signal*/ Eina_Bool quit : 1; /**< set if the exit request was a quit signal */ @@ -546,7 +567,11 @@ struct _Ecore_Event_Signal_Exit /** Exit request event */ #endif }; -struct _Ecore_Event_Signal_Power /** Power event */ +/** + * @struct _Ecore_Event_Signal_Power + * @brief A structure that stores information of a Power event. + */ +struct _Ecore_Event_Signal_Power { void *ext_data; /**< Extension data - not used */ @@ -555,7 +580,11 @@ struct _Ecore_Event_Signal_Power /** Power event */ #endif }; -struct _Ecore_Event_Signal_Realtime /** Realtime event */ +/** + * @struct _Ecore_Event_Signal_Realtime + * @brief A structure that stores information of a Realtime event. + */ +struct _Ecore_Event_Signal_Realtime { int num; /**< The realtime signal's number */ @@ -928,13 +957,21 @@ typedef struct _Ecore_Exe_Event_Del Ecore_Exe_Event_Del; /**< Spawned Exe typedef struct _Ecore_Exe_Event_Data_Line Ecore_Exe_Event_Data_Line; /**< Lines from a child process */ typedef struct _Ecore_Exe_Event_Data Ecore_Exe_Event_Data; /**< Data from a child process */ -struct _Ecore_Exe_Event_Add /** Process add event */ +/** + * @struct _Ecore_Exe_Event_Add + * @brief A structure that stores information of a Process add event. + */ +struct _Ecore_Exe_Event_Add { Ecore_Exe *exe; /**< The handle to the added process */ void *ext_data; /**< Extension data - not used */ }; -struct _Ecore_Exe_Event_Del /** Process exit event */ +/** + * @struct _Ecore_Exe_Event_Del + * @brief A structure that stores information of a Process exit event. + */ +struct _Ecore_Exe_Event_Del { pid_t pid; /**< The process ID of the process that exited */ int exit_code; /**< The exit code of the process */ @@ -948,13 +985,21 @@ struct _Ecore_Exe_Event_Del /** Process exit event */ #endif }; -struct _Ecore_Exe_Event_Data_Line /**< Lines from a child process */ +/** + * @struct _Ecore_Exe_Event_Data_Line + * @brief A structure that stores information of lines data from a child process. + */ +struct _Ecore_Exe_Event_Data_Line { char *line; /**< The bytes of a line of buffered data */ int size; /**< The size of the line buffer in bytes */ }; -struct _Ecore_Exe_Event_Data /** Data from a child process event */ +/** + * @struct _Ecore_Exe_Event_Data + * @brief A structure that stores information of data from a child process event. + */ +struct _Ecore_Exe_Event_Data { Ecore_Exe *exe; /**< The handle to the process */ void *data; /**< the raw binary data from the child process that was received */ @@ -1093,7 +1138,7 @@ EAPI Ecore_Exe_Event_Data *ecore_exe_event_data_get(Ecore_Exe *exe, Ecore_Exe_Fl /** * Frees the given event data. * - * @param e The given event data. + * @param data The given event data. */ EAPI void ecore_exe_event_data_free(Ecore_Exe_Event_Data *data); @@ -1409,7 +1454,19 @@ EAPI Eina_Bool ecore_main_fd_handler_active_get(Ecore_Fd_Handler *fd_handler, Ec */ EAPI void ecore_main_fd_handler_active_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags); +/** + * @brief Create a Ecore_Win32_Handler object and add it to the win32_handlers list. + * @param h The win32 handler. + * @param func The function to add as a callback. + * @param data The data to pass to the callback when it is called. + */ EAPI Ecore_Win32_Handler *ecore_main_win32_handler_add(void *h, Ecore_Win32_Handle_Cb func, const void *data); +/** + * @brief Set Ecore_Win32_Handler object to delete state. + * The handler will be deleted in the _ecore_main_win32_handlers_cleanup function. + * + * @param win32_handler The Ecore_Win32_Handler object. + */ EAPI void *ecore_main_win32_handler_del(Ecore_Win32_Handler *win32_handler); /** @@ -2265,7 +2322,7 @@ EAPI Ecore_Pipe *ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data); /** * Create a pipe with more parameters * - * @param hanlder Same as ecore_pipe_add() + * @param handler Same as ecore_pipe_add() * @param data Same as ecore_pipe_add() * @param fd_read An fd to use for reading or -1 otherwise * @param fd_write An fd to use for writing or -1 otherwise @@ -2273,7 +2330,8 @@ EAPI Ecore_Pipe *ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data); * @param write_survive_fork Should write fd survive a fork * * This is the same as ecore_pipe_add() but with some added parameters. - * + * + * @return A pointer to the new Ecore_Pipe object on success, else NULL. * @see ecore_pipe_add() */ EAPI Ecore_Pipe *ecore_pipe_full_add(Ecore_Pipe_Cb handler, @@ -2942,7 +3000,7 @@ EAPI double ecore_timer_precision_get(void); /** * @brief Sets the precision to be used by timer infrastructure. * - * @param value allowed introduced timeout delay, in seconds. + * @param precision allowed introduced timeout delay, in seconds. * * This sets the precision for @b all timers. The precision determines how much * of an difference from the requested interval is acceptable. One common reason From a598e3db0219b3bb7ba87542d866bb4993f5d3eb Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Fri, 10 Oct 2014 17:13:19 +0200 Subject: [PATCH 18/55] ecore: update missing Ecore_Getopt.h API documentation. --- src/lib/ecore/Ecore_Getopt.h | 714 ++++++++++++++++++++++++++++++++--- 1 file changed, 659 insertions(+), 55 deletions(-) diff --git a/src/lib/ecore/Ecore_Getopt.h b/src/lib/ecore/Ecore_Getopt.h index 33e4dbf1f3..439e021782 100644 --- a/src/lib/ecore/Ecore_Getopt.h +++ b/src/lib/ecore/Ecore_Getopt.h @@ -52,39 +52,54 @@ extern "C" { #endif +/** + * @typedef Ecore_Getopt_Action + * @brief Enumeration that defines the actions to do when parsing command line + * parameters. + */ typedef enum { - ECORE_GETOPT_ACTION_STORE, - ECORE_GETOPT_ACTION_STORE_CONST, - ECORE_GETOPT_ACTION_STORE_TRUE, - ECORE_GETOPT_ACTION_STORE_FALSE, - ECORE_GETOPT_ACTION_CHOICE, - ECORE_GETOPT_ACTION_APPEND, - ECORE_GETOPT_ACTION_COUNT, - ECORE_GETOPT_ACTION_CALLBACK, - ECORE_GETOPT_ACTION_HELP, - ECORE_GETOPT_ACTION_VERSION, - ECORE_GETOPT_ACTION_COPYRIGHT, - ECORE_GETOPT_ACTION_LICENSE, - ECORE_GETOPT_ACTION_BREAK, + ECORE_GETOPT_ACTION_STORE, /**< Store a value */ + ECORE_GETOPT_ACTION_STORE_CONST, /**< Store a const */ + ECORE_GETOPT_ACTION_STORE_TRUE, /**< Store TRUE */ + ECORE_GETOPT_ACTION_STORE_FALSE, /**< Store FALSE */ + ECORE_GETOPT_ACTION_CHOICE, /**< Store a choice between several values */ + ECORE_GETOPT_ACTION_APPEND, /**< Allocate and store a new value of type Ecore_Getopt_Type */ + ECORE_GETOPT_ACTION_COUNT, /**< Store a count number */ + ECORE_GETOPT_ACTION_CALLBACK, /**< Call a callback */ + ECORE_GETOPT_ACTION_HELP, /**< Show help text */ + ECORE_GETOPT_ACTION_VERSION, /**< Show version */ + ECORE_GETOPT_ACTION_COPYRIGHT, /**< Show copyright */ + ECORE_GETOPT_ACTION_LICENSE, /**< Show license */ + ECORE_GETOPT_ACTION_BREAK, /**< Stop parsing options */ ECORE_GETOPT_ACTION_CATEGORY } Ecore_Getopt_Action; +/** + * @typedef Ecore_Getopt_Type + * @brief Enumeration that defines the type of the values to store when using + * append action. + */ typedef enum { - ECORE_GETOPT_TYPE_STR, - ECORE_GETOPT_TYPE_BOOL, - ECORE_GETOPT_TYPE_SHORT, - ECORE_GETOPT_TYPE_INT, - ECORE_GETOPT_TYPE_LONG, - ECORE_GETOPT_TYPE_USHORT, - ECORE_GETOPT_TYPE_UINT, - ECORE_GETOPT_TYPE_ULONG, - ECORE_GETOPT_TYPE_DOUBLE + ECORE_GETOPT_TYPE_STR, /**< Value of type string */ + ECORE_GETOPT_TYPE_BOOL, /**< Value of type boolean */ + ECORE_GETOPT_TYPE_SHORT, /**< Value of type short */ + ECORE_GETOPT_TYPE_INT, /**< Value of type int */ + ECORE_GETOPT_TYPE_LONG, /**< Value of type long */ + ECORE_GETOPT_TYPE_USHORT, /**< Value of type unsigned short */ + ECORE_GETOPT_TYPE_UINT, /**< Value of type unsigned int */ + ECORE_GETOPT_TYPE_ULONG, /**< Value of type unsigned long */ + ECORE_GETOPT_TYPE_DOUBLE /**< Value of type double */ } Ecore_Getopt_Type; +/** + * @typedef Ecore_Getopt_Desc_Arg_Requirement + * @brief Enumeration that defines if the command line options require an + * argument. + */ typedef enum { - ECORE_GETOPT_DESC_ARG_REQUIREMENT_NO = 0, - ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES = 1, - ECORE_GETOPT_DESC_ARG_REQUIREMENT_OPTIONAL = 3 + ECORE_GETOPT_DESC_ARG_REQUIREMENT_NO = 0, /**< Argument is not required */ + ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES = 1, /**< Argument is required */ + ECORE_GETOPT_DESC_ARG_REQUIREMENT_OPTIONAL = 3 /**< Argument is optional */ } Ecore_Getopt_Desc_Arg_Requirement; typedef struct _Ecore_Getopt_Desc_Store Ecore_Getopt_Desc_Store; @@ -103,51 +118,69 @@ typedef union _Ecore_Getopt_Value Ecore_Getopt_Value; #define _ECORE_GETOPT_VALUE_PREDEF 1 #endif +/** + * @union _Ecore_Getopt_Value + * @brief Union listing the types of parameters that can take Getopt values. + */ union _Ecore_Getopt_Value { - char **strp; - unsigned char *boolp; - short *shortp; - int *intp; - long *longp; - unsigned short *ushortp; - unsigned int *uintp; - unsigned long *ulongp; - double *doublep; - Eina_List **listp; - void **ptrp; + char **strp; /**< String pointer */ + unsigned char *boolp; /**< Boolean pointer */ + short *shortp; /**< Short pointer */ + int *intp; /**< Int pointer */ + long *longp; /**< Long pointer */ + unsigned short *ushortp; /**< Unsigned short pointer */ + unsigned int *uintp; /**< Unsigned int pointer */ + unsigned long *ulongp; /**< Unsigned long pointer */ + double *doublep; /**< Double pointer */ + Eina_List **listp; /**< List pointer */ + void **ptrp; /**< Void pointer */ }; +/** + * @struct _Ecore_Getopt_Desc_Store + * @brief Structure used when action is ECORE_GETOPT_ACTION_STORE. It contains + * information about the value to store. + */ struct _Ecore_Getopt_Desc_Store { Ecore_Getopt_Type type; /**< type of data being handled */ - Ecore_Getopt_Desc_Arg_Requirement arg_req; + Ecore_Getopt_Desc_Arg_Requirement arg_req; /**< option argument requirement */ union { - const char *strv; - Eina_Bool boolv; - short shortv; - int intv; - long longv; - unsigned short ushortv; - unsigned int uintv; - unsigned long ulongv; - double doublev; - } def; + const char *strv; /**< String value */ + Eina_Bool boolv; /**< Boolean value */ + short shortv; /**< Short value */ + int intv; /**< Int value */ + long longv; /**< Long value */ + unsigned short ushortv; /**< Unsigned short value */ + unsigned int uintv; /**< Unsigned int value */ + unsigned long ulongv; /**< Unsigned long value */ + double doublev; /**< Double value */ + } def; /**< value of data being handled */ }; +/** + * @struct _Ecore_Getopt_Desc_Callback + * @brief Structure used when action is ECORE_GETOPT_ACTION_CALLBACK. It + * contains information about the callback to call. + */ struct _Ecore_Getopt_Desc_Callback { Eina_Bool (*func)(const Ecore_Getopt *parser, const Ecore_Getopt_Desc *desc, const char *str, void *data, - Ecore_Getopt_Value *storage); - const void *data; - Ecore_Getopt_Desc_Arg_Requirement arg_req; + Ecore_Getopt_Value *storage); /**< function to call as a callback */ + const void *data; /**< data to pass to the callback */ + Ecore_Getopt_Desc_Arg_Requirement arg_req; /**< option argument requirement */ const char *def; }; +/** + * @struct _Ecore_Getopt_Desc + * @brief Structure that describe an option of the command line. + */ struct _Ecore_Getopt_Desc { char shortname; /**< used with a single dash */ @@ -164,9 +197,13 @@ struct _Ecore_Getopt_Desc const Ecore_Getopt_Type append_type; const Ecore_Getopt_Desc_Callback callback; const void *dummy; - } action_param; + } action_param; /**< Action parameter */ }; +/** + * @struct _Ecore_Getopt + * @brief Structure that contains information on all command line options. + */ struct _Ecore_Getopt { const char *prog; /**< to be used when ecore_app_args_get() fails */ @@ -176,215 +213,701 @@ struct _Ecore_Getopt const char *license; /**< if exists, --license will work */ const char *description; /**< long description, possible multiline */ Eina_Bool strict : 1; /**< fail on errors */ - const Ecore_Getopt_Desc descs[]; /* NULL terminated. */ + const Ecore_Getopt_Desc descs[]; /**< A table that contains the description of all the other options (NULL terminated).*/ + }; +/** + * @brief Macro that helps to fill the Ecore_Getopt_Desc table. + */ #define ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, type, arg_requirement, default_value) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_STORE, \ {.store = {type, arg_requirement, default_value}}} +/** + * @brief Macro that fills an option in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param type The option value type. + */ #define ECORE_GETOPT_STORE(shortname, longname, help, type) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, NULL, type, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES, {}) - +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type string. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_STR(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_STR) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type boolean. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_BOOL(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_BOOL) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type short. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_SHORT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_SHORT) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type int. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_INT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_INT) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type long. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_LONG(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_LONG) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type ushort. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_USHORT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_USHORT) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type uint. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_UINT(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_UINT) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type ulong. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_ULONG(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_ULONG) + +/** + * @brief Macro that fill Ecore_Getopt_Desc table with an option of type double. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_DOUBLE(shortname, longname, help) \ ECORE_GETOPT_STORE(shortname, longname, help, ECORE_GETOPT_TYPE_DOUBLE) +/** + * Macro that helps to fill the Ecore_Getopt_Desc table with a metavar after + * the description of the option. + */ #define ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, type) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, type, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES, {}) +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type string and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_STR(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_STR) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type boolean and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_BOOL(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_BOOL) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type short and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_SHORT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_SHORT) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type int and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_INT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_INT) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type long and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_LONG(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_LONG) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned short and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_USHORT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_USHORT) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned int and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_UINT(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_UINT) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned long and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_ULONG(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_ULONG) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type double and metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + */ #define ECORE_GETOPT_STORE_METAVAR_DOUBLE(shortname, longname, help, metavar) \ ECORE_GETOPT_STORE_METAVAR(shortname, longname, help, metavar, ECORE_GETOPT_TYPE_DOUBLE) +/** + * Macro that helps to fill the Ecore_Getopt_Desc table with a default value. + */ #define ECORE_GETOPT_STORE_DEF(shortname, longname, help, type, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, NULL, type, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_OPTIONAL, \ default_value) +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type string and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_STR(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_STR, \ {.strv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type boolean and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_BOOL(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_BOOL, \ {.boolv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type short and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_SHORT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_SHORT, \ {.shortv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type int and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_INT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_INT, \ {.intv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type long and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_LONG(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_LONG, \ {.longv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned short and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_USHORT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_USHORT, \ {.ushortv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned int and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_UINT(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_UINT, \ {.uintv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type unsigned long and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_ULONG(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_ULONG, \ {.ulongv = default_value}) + +/** + * @brief Fill Ecore_Getopt_Desc table with an option of type double and default value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_DEF_DOUBLE(shortname, longname, help, default_value) \ ECORE_GETOPT_STORE_DEF(shortname, longname, help, \ ECORE_GETOPT_TYPE_DOUBLE, \ {.doublev = default_value}) +/** + * @brief Fill full string type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_STR(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_STR, \ arg_requirement, \ {.strv = default_value}) + +/** + * @brief Fill full boolean type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_BOOL(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_BOOL, \ arg_requirement, \ {.boolv = default_value}) + +/** + * @brief Fill full short type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_SHORT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_SHORT, \ arg_requirement, \ {.shortv = default_value}) + +/** + * @brief Fill full int type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_INT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_INT, \ arg_requirement, \ {.intv = default_value}) + +/** + * @brief Fill full long type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_LONG(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_LONG, \ arg_requirement, \ {.longv = default_value}) + +/** + * @brief Fill full unsigned short type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_USHORT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_USHORT, \ arg_requirement, \ {.ushortv = default_value}) + +/** + * @brief Fill full unsigned int type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_UINT(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_UINT, \ arg_requirement, \ {.uintv = default_value}) + +/** + * @brief Fill full unsigned long type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_ULONG(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_ULONG, \ arg_requirement, \ {.ulongv = default_value}) + +/** + * @brief Fill full double type option description in Ecore_Getopt_Desc table. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param arg_requirement The option argument requirements. + * @param default_value The default value for the parameter of the option. + */ #define ECORE_GETOPT_STORE_FULL_DOUBLE(shortname, longname, help, metavar, arg_requirement, default_value) \ ECORE_GETOPT_STORE_FULL(shortname, longname, help, metavar, \ ECORE_GETOPT_TYPE_DOUBLE, \ arg_requirement, \ {.doublev = default_value}) +/** + * @brief Fill Ecore_Getopt_Desc table with a constant value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param value The constant value to store. + */ #define ECORE_GETOPT_STORE_CONST(shortname, longname, help, value) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_STORE_CONST, \ {.store_const = value}} + +/** + * @brief Fill Ecore_Getopt_Desc table with a true boolean value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_TRUE(shortname, longname, help) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_STORE_TRUE, \ {.dummy = NULL}} + +/** + * @brief Fill Ecore_Getopt_Desc table with a false boolean value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_STORE_FALSE(shortname, longname, help) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_STORE_FALSE, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a true boolean value. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param choices_array An string array of different choices. + */ #define ECORE_GETOPT_CHOICE(shortname, longname, help, choices_array) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_CHOICE, \ {.choices = choices_array}} + +/** + * @brief Fill Ecore_Getopt_Desc table with a choice. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param choices_array An string array of different choices. + */ #define ECORE_GETOPT_CHOICE_METAVAR(shortname, longname, help, metavar, choices_array) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_CHOICE, \ {.choices = choices_array}} +/** + * @brief Fill Ecore_Getopt_Desc table with an append action. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param sub_type The type of the new value to store. + */ #define ECORE_GETOPT_APPEND(shortname, longname, help, sub_type) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_APPEND, \ {.append_type = sub_type}} + +/** + * @brief Fill Ecore_Getopt_Desc table with an append action and a metavar. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param type The type of the new value to store. + */ #define ECORE_GETOPT_APPEND_METAVAR(shortname, longname, help, metavar, type) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_APPEND, \ {.append_type = type}} +/** + * @brief Fill Ecore_Getopt_Desc table with an count action. + * + * This will store the number of time the option has been passed to the command + * line. + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_COUNT(shortname, longname, help) \ {shortname, longname, help, NULL, ECORE_GETOPT_ACTION_COUNT, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with an callback action and argument requirements. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param callback_func The callback function to call. + * @param callback_data The data to pass to the callback. + * @param argument_requirement the required arguments to this option. + * @param default_value The default values for these arguments. + */ #define ECORE_GETOPT_CALLBACK_FULL(shortname, longname, help, metavar, callback_func, callback_data, argument_requirement, default_value) \ {shortname, longname, help, metavar, ECORE_GETOPT_ACTION_CALLBACK, \ {.callback = {callback_func, callback_data, \ argument_requirement, default_value}}} + +/** + * @brief Fill Ecore_Getopt_Desc table with an callback action and no arguments. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param callback_func The callback function to call. + * @param callback_data The data to pass to the callback. + */ #define ECORE_GETOPT_CALLBACK_NOARGS(shortname, longname, help, callback_func, callback_data) \ ECORE_GETOPT_CALLBACK_FULL(shortname, longname, help, NULL, \ callback_func, callback_data, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_NO, \ NULL) + +/** + * @brief Fill Ecore_Getopt_Desc table with an callback action. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + * @param metavar The metavar message concerning the parameter of the option. + * @param callback_func The callback function to call. + * @param callback_data The data to pass to the callback. + */ #define ECORE_GETOPT_CALLBACK_ARGS(shortname, longname, help, metavar, callback_func, callback_data) \ ECORE_GETOPT_CALLBACK_FULL(shortname, longname, help, metavar, \ callback_func, callback_data, \ ECORE_GETOPT_DESC_ARG_REQUIREMENT_YES, \ NULL) +/** + * @brief Fill Ecore_Getopt_Desc table with a help action. + * + * @param shortname The help option short name. + * @param longname The help option long name. + */ #define ECORE_GETOPT_HELP(shortname, longname) \ {shortname, longname, "show this message.", "CATEGORY", \ ECORE_GETOPT_ACTION_HELP, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a version action. + * + * @param shortname The version option short name. + * @param longname The version option long name. + */ #define ECORE_GETOPT_VERSION(shortname, longname) \ {shortname, longname, "show program version.", NULL, \ ECORE_GETOPT_ACTION_VERSION, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a copyright action. + * + * @param shortname The copyright option short name. + * @param longname The copyright option long name. + */ #define ECORE_GETOPT_COPYRIGHT(shortname, longname) \ {shortname, longname, "show copyright.", NULL, \ ECORE_GETOPT_ACTION_COPYRIGHT, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a license action. + * + * @param shortname The license option short name. + * @param longname The license option long name. + */ #define ECORE_GETOPT_LICENSE(shortname, longname) \ {shortname, longname, "show license.", NULL, \ ECORE_GETOPT_ACTION_LICENSE, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a break action. + * + * @param shortname The option short name. + * @param longname The option long name. + */ #define ECORE_GETOPT_BREAK(shortname, longname) \ {shortname, longname, "stop parsing options.", NULL, \ ECORE_GETOPT_ACTION_BREAK, \ {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a break action with help message. + * + * @param shortname The option short name. + * @param longname The option long name. + * @param help The help message concerning this option. + */ #define ECORE_GETOPT_BREAK_STR(shortname, longname, help) \ {shortname, longname, help, NULL, \ ECORE_GETOPT_ACTION_BREAK, \ @@ -393,27 +916,108 @@ struct _Ecore_Getopt #define ECORE_GETOPT_CATEGORY(name, help) \ {0, name, help, NULL, ECORE_GETOPT_ACTION_CATEGORY, {.dummy = NULL}} +/** + * @brief Fill Ecore_Getopt_Desc table with a sentinel to indicate the end of descriptions. + * + */ #define ECORE_GETOPT_SENTINEL {0, NULL, NULL, NULL, 0, {.dummy = NULL}} +/** + * @brief options that store a single value in a variable of type string. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_STR(val) {.strp = &(val)} + +/** + * @brief options that store a single value in a variable of type boolean. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_BOOL(val) {.boolp = &(val)} + +/** + * @brief options that store a single value in a variable of type short. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_SHORT(val) {.shortp = &(val)} + +/** + * @brief options that store a single value in a variable of type int. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_INT(val) {.intp = &(val)} + +/** + * @brief options that store a single value in a variable of type long. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_LONG(val) {.longp = &(val)} + +/** + * @brief options that store a single value in a variable of type unsigned short. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_USHORT(val) {.ushortp = &(val)} + +/** + * @brief options that store a single value in a variable of type unsigned int. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_UINT(val) {.uintp = &(val)} + +/** + * @brief options that store a single value in a variable of type unsigned long. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_ULONG(val) {.ulongp = &(val)} + +/** + * @brief options that store a single value in a variable of type double. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_DOUBLE(val) {.doublep = &(val)} + +/** + * @brief options that store a single value in a variable of type pointer. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_PTR(val) {.ptrp = &(val)} + +/** + * @brief options that store a single value in a variable of type pointer casted. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_PTR_CAST(val) {.ptrp = (void **)&(val)} + +/** + * @brief options that store a single value in a variable of type list. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_LIST(val) {.listp = &(val)} + +/** + * @brief options that store a NULL value. + * + * @param val The value to store. + */ #define ECORE_GETOPT_VALUE_NONE {.ptrp = NULL} /** * Show nicely formatted help message for the given parser. * * @param fp The file the message will be printed on. - * @param parser The parser to be used. + * @param info The structure containing information about command line options. * * @see ecore_getopt_help_category() */ @@ -423,7 +1027,7 @@ EAPI void ecore_getopt_help(FILE *fp, const Ecore_Getopt *info); * Show help for a single category (along with program usage and description). * * @param fp The file the message will be printed on. - * @param parser The parser to be used. + * @param info The structure containing information about command line options. * @param category The category to print. * * @return @c EINA_TRUE when the category exists, @c EINA_FALSE otherwise. From 8fdf3241b50914b68c8fc05ecfdfbee143363ab7 Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Tue, 14 Oct 2014 11:23:31 +0200 Subject: [PATCH 19/55] ecore_con: update missing Ecore_con.h API documentation. --- src/lib/ecore_con/Ecore_Con.h | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/lib/ecore_con/Ecore_Con.h b/src/lib/ecore_con/Ecore_Con.h index a5adb2558b..6cfea2eff3 100644 --- a/src/lib/ecore_con/Ecore_Con.h +++ b/src/lib/ecore_con/Ecore_Con.h @@ -426,7 +426,7 @@ typedef struct _Ecore_Con_Event_Url_Progress Ecore_Con_Event_Url_Progress; */ struct _Ecore_Con_Event_Client_Add { - Ecore_Con_Client *client; /** the client that connected */ + Ecore_Con_Client *client; /**< the client that connected */ }; /** @@ -436,7 +436,7 @@ struct _Ecore_Con_Event_Client_Add */ struct _Ecore_Con_Event_Client_Upgrade { - Ecore_Con_Client *client; /** the client that completed handshake */ + Ecore_Con_Client *client; /**< the client that completed handshake */ }; /** @@ -445,7 +445,7 @@ struct _Ecore_Con_Event_Client_Upgrade */ struct _Ecore_Con_Event_Client_Del { - Ecore_Con_Client *client; /** the client that was lost */ + Ecore_Con_Client *client; /**< the client that was lost */ }; /** @@ -454,7 +454,7 @@ struct _Ecore_Con_Event_Client_Del */ struct _Ecore_Con_Event_Client_Error { - Ecore_Con_Client *client; /** the client for which an error occurred */ + Ecore_Con_Client *client; /**< the client for which an error occurred */ char *error; /**< the error string describing what happened */ }; @@ -464,7 +464,7 @@ struct _Ecore_Con_Event_Client_Error */ struct _Ecore_Con_Event_Server_Add { - Ecore_Con_Server *server; /** the server that was connected to */ + Ecore_Con_Server *server; /**< the server that was connected to */ }; /** @@ -474,7 +474,7 @@ struct _Ecore_Con_Event_Server_Add */ struct _Ecore_Con_Event_Server_Upgrade { - Ecore_Con_Server *server; /** the server that was connected to */ + Ecore_Con_Server *server; /**< the server that was connected to */ }; /** @@ -483,7 +483,7 @@ struct _Ecore_Con_Event_Server_Upgrade */ struct _Ecore_Con_Event_Server_Del { - Ecore_Con_Server *server; /** the client that was lost */ + Ecore_Con_Server *server; /**< the client that was lost */ }; /** @@ -492,7 +492,7 @@ struct _Ecore_Con_Event_Server_Del */ struct _Ecore_Con_Event_Server_Error { - Ecore_Con_Server *server; /** the server for which an error occurred */ + Ecore_Con_Server *server; /**< the server for which an error occurred */ char *error; /**< the error string describing what happened */ }; From 55623537ea7e03bb9782f7336e40e841392c90d8 Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Fri, 3 Oct 2014 15:42:43 +0200 Subject: [PATCH 20/55] ecore_con: update missing Ecore_Con_Eet.h API documentation. --- src/lib/ecore_con/Ecore_Con_Eet.h | 205 ++++++++++++++++++++++++++++++ 1 file changed, 205 insertions(+) diff --git a/src/lib/ecore_con/Ecore_Con_Eet.h b/src/lib/ecore_con/Ecore_Con_Eet.h index bdf0d2d605..95373c46b8 100644 --- a/src/lib/ecore_con/Ecore_Con_Eet.h +++ b/src/lib/ecore_con/Ecore_Con_Eet.h @@ -31,43 +31,248 @@ # endif #endif +/** + * @defgroup Ecore_Con_Eet_Group Ecore_Con_Eet - Eet connection functions + * @ingroup Ecore + * + * The Ecore Connection Eet library ( @c Ecore_Con_Eet) adds @c Eet data + * serialization features to Ecore Connection objects. Its main aim is to + * provide a way to send @c Eet data streams to another program through sockets + * using @c Ecore_Con objects. + */ + typedef struct _Ecore_Con_Eet Ecore_Con_Eet; typedef struct _Ecore_Con_Reply Ecore_Con_Reply; +/** + * @typedef Ecore_Con_Eet_Data_Cb + * @brief Called when an Ecore_Con_Eet object receives data. + */ typedef void (*Ecore_Con_Eet_Data_Cb)(void *data, Ecore_Con_Reply *reply, const char *protocol_name, void *value); + +/** + * @typedef Ecore_Con_Eet_Raw_Data_Cb + * @brief Called when an Ecore_Con_Eet object receives raw data. + */ typedef void (*Ecore_Con_Eet_Raw_Data_Cb)(void *data, Ecore_Con_Reply *reply, const char *protocol_name, const char *section, void *value, size_t length); + +/** + * @typedef Ecore_Con_Eet_Client_Cb + * @brief Called when a client connects to the server. + */ typedef Eina_Bool (*Ecore_Con_Eet_Client_Cb)(void *data, Ecore_Con_Reply *reply, Ecore_Con_Client *conn); + +/** + * @typedef Ecore_Con_Eet_Server_Cb + * @brief Called when the server has accepted the connection of the client. + */ typedef Eina_Bool (*Ecore_Con_Eet_Server_Cb)(void *data, Ecore_Con_Reply *reply, Ecore_Con_Server *conn); +/** + * Create a Ecore_Con_Eet server. + * + * @param server An existing Ecore_Con_Server that have been previously + * created by the server program with @ref + * ecore_con_server_add. + * + * @return A new Ecore_Con_Eet server. + */ EAPI Ecore_Con_Eet *ecore_con_eet_server_new(Ecore_Con_Server *server); + +/** + * Create a Ecore_Con_Eet client. + * + * @param server An existing Ecore_Con_Server that have been previously + * returned by a call to @ref ecore_con_server_connect in the + * client program. + * + * @return A new Ecore_Con_Eet client. + */ EAPI Ecore_Con_Eet *ecore_con_eet_client_new(Ecore_Con_Server *server); + +/** + * Free an existing Ecore_Con_Eet object. + * + * @param server An existing Ecore_Con_Eet object that have been previously + * allocated by a @ref ecore_con_eet_server_new or @ref + * ecore_con_eet_client_new. + * + */ EAPI void ecore_con_eet_server_free(Ecore_Con_Eet *ece); +/** + * Register an @c Eet data descriptor on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param name The name of the Eet stream to connect. + * @param edd A Eet data descriptor that describes the data organization + * in the Eet stream. + * + */ EAPI void ecore_con_eet_register(Ecore_Con_Eet *ece, const char *name, Eet_Data_Descriptor *edd); +/** + * Register a data callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param name The name of the Eet stream to connect. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + * + */ EAPI void ecore_con_eet_data_callback_add(Ecore_Con_Eet *ece, const char *name, Ecore_Con_Eet_Data_Cb func, const void *data); + +/** + * Remove a data callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param name The name of the Eet stream to remove callback on. + * + */ EAPI void ecore_con_eet_data_callback_del(Ecore_Con_Eet *ece, const char *name); +/** + * Register a raw data callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param name The name of the raw Eet stream to connect. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + * + */ EAPI void ecore_con_eet_raw_data_callback_add(Ecore_Con_Eet *ece, const char *name, Ecore_Con_Eet_Raw_Data_Cb func, const void *data); + +/** + * Remove a raw data callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param name The name of the raw Eet stream to remove callback on. + * + */ EAPI void ecore_con_eet_raw_data_callback_del(Ecore_Con_Eet *ece, const char *name); +/** + * Register a client connect callback on a Ecore_Con_Eet object. + * @brief This callback can be registered on the server program to know when a + * client connects. + * + * @param ece An Ecore_Con_Eet object. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + */ EAPI void ecore_con_eet_client_connect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); + +/** + * Remove a client connect callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param func The callback to remove. + * @param data The data passed to this function at the callback registration. + */ EAPI void ecore_con_eet_client_connect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); +/** + * Register a client disconnect callback on a Ecore_Con_Eet object. + * @brief This callback can be registered on the server program to know when a + * client disconnects. + * + * @param ece An Ecore_Con_Eet object. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + */ EAPI void ecore_con_eet_client_disconnect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); + +/** + * Remove a client disconnect callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param func The callback to remove. + * @param data The data passed to this function at the callback registration. + */ EAPI void ecore_con_eet_client_disconnect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Client_Cb func, const void *data); +/** + * Register a server connect callback on a Ecore_Con_Eet object. + * @brief This callback can be registered on the client program to be called + * when it has been connected to the server. + * + * @param ece An Ecore_Con_Eet object. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + */ EAPI void ecore_con_eet_server_connect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); + +/** + * Remove a server connect callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param func The callback to remove. + * @param data The data passed to this function at the callback registration. + */ EAPI void ecore_con_eet_server_connect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); +/** + * Register a server disconnect callback on a Ecore_Con_Eet object. + * @brief This callback can be registered on the client program to be called + * when it has been disconnected from the server. + * + * @param ece An Ecore_Con_Eet object. + * @param func The function to call as a callback. + * @param data The data to pass to the callback. + */ EAPI void ecore_con_eet_server_disconnect_callback_add(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); + +/** + * Remove a server disconnect callback on a Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param func The callback to remove. + * @param data The data passed to this function at the callback registration. + */ EAPI void ecore_con_eet_server_disconnect_callback_del(Ecore_Con_Eet *ece, Ecore_Con_Eet_Server_Cb func, const void *data); +/** + * Attach data to an Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @param data The data to attach to the Ecore_Con_Eet object. + */ EAPI void ecore_con_eet_data_set(Ecore_Con_Eet *ece, const void *data); + +/** + * Get the data attached to an Ecore_Con_Eet object. + * + * @param ece An Ecore_Con_Eet object. + * @return The data attached to the Ecore_Con_Eet object. + */ EAPI void *ecore_con_eet_data_get(Ecore_Con_Eet *ece); +/** + * Get the Ecore_Con_Eet object corresponding to the Ecore_Con_Reply object. + * + * @param reply An Ecore_Con_Reply object. + * @return The corresponding Ecore_Con_Eet object. + */ EAPI Ecore_Con_Eet *ecore_con_eet_reply(Ecore_Con_Reply *reply); + +/** + * Send some data using a protocol type. + * + * @param reply An Ecore_Con_Reply object. + * @param protocol_name The protocol type to use. + * @param value The data to send. + */ EAPI void ecore_con_eet_send(Ecore_Con_Reply *reply, const char *protocol_name, void *value); + +/** + * Send some raw data using a protocol type. + * + * @param reply An Ecore_Con_Reply object. + * @param protocol_name The protocol type to use. + * @param section The section to add to the protocol. + * @param value The data to send. + * @param length The data length. + */ EAPI void ecore_con_eet_raw_send(Ecore_Con_Reply *reply, const char *protocol_name, const char *section, void *value, unsigned int length); #endif From 4a71cb268f4dff68949ac35d20c67ebd5c07a3ea Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Fri, 3 Oct 2014 18:28:51 +0200 Subject: [PATCH 21/55] ecore_imf: update missing Ecore_IMF.h API documentation. --- src/lib/ecore_imf/Ecore_IMF.h | 209 ++++++++++++++++++++++++++++------ 1 file changed, 172 insertions(+), 37 deletions(-) diff --git a/src/lib/ecore_imf/Ecore_IMF.h b/src/lib/ecore_imf/Ecore_IMF.h index e77437270e..374c0904a1 100644 --- a/src/lib/ecore_imf/Ecore_IMF.h +++ b/src/lib/ecore_imf/Ecore_IMF.h @@ -78,6 +78,11 @@ extern "C" { */ /* ecore_imf_context_input_panel_event_callback_add() flag */ + +/** + * @typedef Ecore_IMF_Input_Panel_Event + * Enum containing input panel events. + */ typedef enum { ECORE_IMF_INPUT_PANEL_STATE_EVENT, /**< called when the state of the input panel is changed. @since 1.7 */ @@ -88,6 +93,10 @@ typedef enum ECORE_IMF_CANDIDATE_PANEL_GEOMETRY_EVENT /**< called when the size of the candidate word panel is changed. @since 1.7 */ } Ecore_IMF_Input_Panel_Event; +/** + * @typedef Ecore_IMF_Input_Panel_State + * Enum containing input panel state notifications. + */ typedef enum { ECORE_IMF_INPUT_PANEL_STATE_SHOW, /**< Notification after the display of the input panel @since 1.7 */ @@ -95,12 +104,20 @@ typedef enum ECORE_IMF_INPUT_PANEL_STATE_WILL_SHOW /**< Notification prior to the display of the input panel @since 1.7 */ } Ecore_IMF_Input_Panel_State; +/** + * @typedef Ecore_IMF_Input_Panel_Shift_Mode + * Enum containing input shift mode states. + */ typedef enum { ECORE_IMF_INPUT_PANEL_SHIFT_MODE_OFF, /**< @since 1.7 */ ECORE_IMF_INPUT_PANEL_SHIFT_MODE_ON /**< @since 1.7 */ } Ecore_IMF_Input_Panel_Shift_Mode; +/** + * @typedef Ecore_IMF_Candidate_Panel_State + * Enum containing candidate word panel state notifications. + */ typedef enum { ECORE_IMF_CANDIDATE_PANEL_SHOW, /**< Notification after the display of the candidate word panel @since 1.7 */ @@ -139,6 +156,13 @@ EAPI extern int ECORE_IMF_EVENT_PREEDIT_CHANGED; EAPI extern int ECORE_IMF_EVENT_COMMIT; EAPI extern int ECORE_IMF_EVENT_DELETE_SURROUNDING; +/** + * @typedef Ecore_IMF_Event_Cb + * + * @brief Called when a Ecore_IMF event happens. + * + * @see ecore_imf_context_event_callback_add() + */ typedef void (*Ecore_IMF_Event_Cb) (void *data, Ecore_IMF_Context *ctx, void *event_info); /** @@ -214,6 +238,10 @@ typedef enum ECORE_IMF_MOUSE_TRIPLE_CLICK = 1 << 1 /**< A triple click */ } Ecore_IMF_Mouse_Flags; +/** + * @typedef Ecore_IMF_Input_Mode + * Type for Ecore_IMF input mode + */ typedef enum { ECORE_IMF_INPUT_MODE_ALPHA = 1 << 0, @@ -362,27 +390,47 @@ typedef enum ECORE_IMF_BIDI_DIRECTION_RTL /**< The Right to Left mode @since 1.12 */ } Ecore_IMF_BiDi_Direction; +/** + * @struct _Ecore_IMF_Event_Preedit_Start + * @brief The structure type used with the Preedit_Start Input Method event + */ struct _Ecore_IMF_Event_Preedit_Start { Ecore_IMF_Context *ctx; }; +/** + * @struct _Ecore_IMF_Event_Preedit_End + * @brief The structure type used with the Preedit_End Input Method event + */ struct _Ecore_IMF_Event_Preedit_End { Ecore_IMF_Context *ctx; }; +/** + * @struct _Ecore_IMF_Event_Preedit_Changed + * @brief The structure type used with the Preedit_Changed Input Method event + */ struct _Ecore_IMF_Event_Preedit_Changed { Ecore_IMF_Context *ctx; }; +/** + * @struct _Ecore_IMF_Event_Commit + * @brief The structure type used with the Commit Input Method event + */ struct _Ecore_IMF_Event_Commit { Ecore_IMF_Context *ctx; char *str; }; +/** + * @struct _Ecore_IMF_Event_Delete_Surrounding + * @brief The structure type used with the Delete_Surrounding Input Method event + */ struct _Ecore_IMF_Event_Delete_Surrounding { Ecore_IMF_Context *ctx; @@ -390,6 +438,10 @@ struct _Ecore_IMF_Event_Delete_Surrounding int n_chars; }; +/** + * @struct _Ecore_IMF_Event_Selection + * @brief The structure type used with the Selection Input Method event + */ struct _Ecore_IMF_Event_Selection { Ecore_IMF_Context *ctx; @@ -397,6 +449,10 @@ struct _Ecore_IMF_Event_Selection int end; }; +/** + * @struct _Ecore_IMF_Event_Mouse_Down + * @brief The structure type used with the Mouse_Down event + */ struct _Ecore_IMF_Event_Mouse_Down { int button; /**< The button which has been pressed */ @@ -412,6 +468,10 @@ struct _Ecore_IMF_Event_Mouse_Down unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Mouse_Up + * @brief The structure type used with the Mouse_Up event + */ struct _Ecore_IMF_Event_Mouse_Up { int button; /**< The button which has been pressed */ @@ -427,6 +487,10 @@ struct _Ecore_IMF_Event_Mouse_Up unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Mouse_In + * @brief The structure type used with the Mouse_In event + */ struct _Ecore_IMF_Event_Mouse_In { int buttons; @@ -441,6 +505,10 @@ struct _Ecore_IMF_Event_Mouse_In unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Mouse_Out + * @brief The structure type used with the Mouse_Out event + */ struct _Ecore_IMF_Event_Mouse_Out { int buttons; @@ -455,6 +523,10 @@ struct _Ecore_IMF_Event_Mouse_Out unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Mouse_Move + * @brief The structure type used with the Mouse_Move event + */ struct _Ecore_IMF_Event_Mouse_Move { int buttons; @@ -471,6 +543,10 @@ struct _Ecore_IMF_Event_Mouse_Move unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Mouse_Wheel + * @brief The structure type used with the Mouse_Wheel event + */ struct _Ecore_IMF_Event_Mouse_Wheel { int direction; /* 0 = default up/down wheel */ @@ -486,6 +562,10 @@ struct _Ecore_IMF_Event_Mouse_Wheel unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Key_Down + * @brief The structure type used with the Key_Down event + */ struct _Ecore_IMF_Event_Key_Down { const char *keyname; /**< The string name of the key pressed */ @@ -497,6 +577,10 @@ struct _Ecore_IMF_Event_Key_Down unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @struct _Ecore_IMF_Event_Key_Up + * @brief The structure type used with the Key_Up event + */ struct _Ecore_IMF_Event_Key_Up { const char *keyname; /**< The string name of the key pressed */ @@ -508,6 +592,9 @@ struct _Ecore_IMF_Event_Key_Up unsigned int timestamp; /**< The timestamp when the event occurred */ }; +/** + * @brief A union of IMF events. + */ union _Ecore_IMF_Event { Ecore_IMF_Event_Mouse_Down mouse_down; @@ -520,6 +607,10 @@ union _Ecore_IMF_Event Ecore_IMF_Event_Key_Up key_up; }; +/** + * @struct _Ecore_IMF_Preedit_Attr + * @brief Structure that contains preedit attribute information. + */ struct _Ecore_IMF_Preedit_Attr { Ecore_IMF_Preedit_Type preedit_type; /**< preedit style type */ @@ -527,47 +618,58 @@ struct _Ecore_IMF_Preedit_Attr unsigned int end_index; /**< end index of the range (in bytes) */ }; +/** + * @struct _Ecore_IMF_Context_Class + * @brief Structure used when creating a new Input Method Context. This + * structure is mainly used by modules implementing the Input Method Context + * interface. + * + */ struct _Ecore_IMF_Context_Class { - void (*add) (Ecore_IMF_Context *ctx); - void (*del) (Ecore_IMF_Context *ctx); - void (*client_window_set) (Ecore_IMF_Context *ctx, void *window); - void (*client_canvas_set) (Ecore_IMF_Context *ctx, void *canvas); - void (*show) (Ecore_IMF_Context *ctx); - void (*hide) (Ecore_IMF_Context *ctx); - void (*preedit_string_get) (Ecore_IMF_Context *ctx, char **str, int *cursor_pos); - void (*focus_in) (Ecore_IMF_Context *ctx); - void (*focus_out) (Ecore_IMF_Context *ctx); - void (*reset) (Ecore_IMF_Context *ctx); - void (*cursor_position_set) (Ecore_IMF_Context *ctx, int cursor_pos); - void (*use_preedit_set) (Ecore_IMF_Context *ctx, Eina_Bool use_preedit); - void (*input_mode_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Mode input_mode); - Eina_Bool (*filter_event) (Ecore_IMF_Context *ctx, Ecore_IMF_Event_Type type, Ecore_IMF_Event *event); - void (*preedit_string_with_attributes_get) (Ecore_IMF_Context *ctx, char **str, Eina_List **attrs, int *cursor_pos); - void (*prediction_allow_set)(Ecore_IMF_Context *ctx, Eina_Bool prediction); - void (*autocapital_type_set)(Ecore_IMF_Context *ctx, Ecore_IMF_Autocapital_Type autocapital_type); - void (*control_panel_show) (Ecore_IMF_Context *ctx); - void (*control_panel_hide) (Ecore_IMF_Context *ctx); - void (*input_panel_layout_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Layout layout); - Ecore_IMF_Input_Panel_Layout (*input_panel_layout_get) (Ecore_IMF_Context *ctx); - void (*input_panel_language_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Lang lang); - Ecore_IMF_Input_Panel_Lang (*input_panel_language_get) (Ecore_IMF_Context *ctx); - void (*cursor_location_set) (Ecore_IMF_Context *ctx, int x, int y, int w, int h); - void (*input_panel_imdata_set)(Ecore_IMF_Context *ctx, const void* data, int len); - void (*input_panel_imdata_get)(Ecore_IMF_Context *ctx, void* data, int *len); - void (*input_panel_return_key_type_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Return_Key_Type return_key_type); - void (*input_panel_return_key_disabled_set) (Ecore_IMF_Context *ctx, Eina_Bool disabled); - void (*input_panel_caps_lock_mode_set) (Ecore_IMF_Context *ctx, Eina_Bool mode); - void (*input_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); - Ecore_IMF_Input_Panel_State (*input_panel_state_get) (Ecore_IMF_Context *ctx); - void (*input_panel_event_callback_add) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value), void *data); - void (*input_panel_event_callback_del) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value)); - void (*input_panel_language_locale_get) (Ecore_IMF_Context *ctx, char **lang); - void (*candidate_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); - void (*input_hint_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Hints input_hints); - void (*bidi_direction_set) (Ecore_IMF_Context *ctx, Ecore_IMF_BiDi_Direction direction); + void (*add) (Ecore_IMF_Context *ctx); /**< Create the Input Method Context */ + void (*del) (Ecore_IMF_Context *ctx); /**< Delete the Input Method Context */ + void (*client_window_set) (Ecore_IMF_Context *ctx, void *window); /**< Set the client window for the Input Method Context */ + void (*client_canvas_set) (Ecore_IMF_Context *ctx, void *canvas); /**< Set the client canvas for the Input Method Context */ + void (*show) (Ecore_IMF_Context *ctx); /**< Show the Input Method Context */ + void (*hide) (Ecore_IMF_Context *ctx); /**< Hide the Input Method Context */ + void (*preedit_string_get) (Ecore_IMF_Context *ctx, char **str, int *cursor_pos); /**< Return current preedit string and cursor position */ + void (*focus_in) (Ecore_IMF_Context *ctx); /**< Input Method context widget has gained focus */ + void (*focus_out) (Ecore_IMF_Context *ctx); /**< Input Method context widget has lost focus */ + void (*reset) (Ecore_IMF_Context *ctx); /**< A change has been made */ + void (*cursor_position_set) (Ecore_IMF_Context *ctx, int cursor_pos); /**< Cursor position changed */ + void (*use_preedit_set) (Ecore_IMF_Context *ctx, Eina_Bool use_preedit); /**< Use preedit string to display feedback */ + void (*input_mode_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Mode input_mode); /**< Set the input mode */ + Eina_Bool (*filter_event) (Ecore_IMF_Context *ctx, Ecore_IMF_Event_Type type, Ecore_IMF_Event *event); /**< Internally handle an event */ + void (*preedit_string_with_attributes_get) (Ecore_IMF_Context *ctx, char **str, Eina_List **attrs, int *cursor_pos); /**< return current preedit string, attributes, and cursor position */ + void (*prediction_allow_set)(Ecore_IMF_Context *ctx, Eina_Bool prediction); /**< Allow text prediction */ + void (*autocapital_type_set)(Ecore_IMF_Context *ctx, Ecore_IMF_Autocapital_Type autocapital_type); /**< Set auto-capitalization type */ + void (*control_panel_show) (Ecore_IMF_Context *ctx); /**< Show the control panel */ + void (*control_panel_hide) (Ecore_IMF_Context *ctx); /**< Hide the control panel */ + void (*input_panel_layout_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Layout layout); /**< Set the layout of the input panel */ + Ecore_IMF_Input_Panel_Layout (*input_panel_layout_get) (Ecore_IMF_Context *ctx); /**< Return the current layout of the input panel */ + void (*input_panel_language_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Lang lang); /**< Set the language of the input panel */ + Ecore_IMF_Input_Panel_Lang (*input_panel_language_get) (Ecore_IMF_Context *ctx); /**< Get the current language of the input panel */ + void (*cursor_location_set) (Ecore_IMF_Context *ctx, int x, int y, int w, int h); /**< Set the cursor location */ + void (*input_panel_imdata_set)(Ecore_IMF_Context *ctx, const void* data, int len); /**< Set panel-specific data to the input panel */ + void (*input_panel_imdata_get)(Ecore_IMF_Context *ctx, void* data, int *len); /**< Get current panel-specific data from the input panel */ + void (*input_panel_return_key_type_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Return_Key_Type return_key_type); /**< Set the return key theme of the input panel based on return key type provided */ + void (*input_panel_return_key_disabled_set) (Ecore_IMF_Context *ctx, Eina_Bool disabled); /**< Disable return key of the input panel */ + void (*input_panel_caps_lock_mode_set) (Ecore_IMF_Context *ctx, Eina_Bool mode); /**< Set input panel caps lock mode */ + void (*input_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); /**< Return input panel geometry */ + Ecore_IMF_Input_Panel_State (*input_panel_state_get) (Ecore_IMF_Context *ctx); /**< Return input panel state */ + void (*input_panel_event_callback_add) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value), void *data); /**< Add a callback on input panel state,language,mode change */ + void (*input_panel_event_callback_del) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Panel_Event type, void (*func) (void *data, Ecore_IMF_Context *ctx, int value)); /**< Delete the input panel event callback */ + void (*input_panel_language_locale_get) (Ecore_IMF_Context *ctx, char **lang); /**< Return the current language locale */ + void (*candidate_panel_geometry_get)(Ecore_IMF_Context *ctx, int *x, int *y, int *w, int *h); /**< Return the candidate panel geometry */ + void (*input_hint_set) (Ecore_IMF_Context *ctx, Ecore_IMF_Input_Hints input_hints); /**< Sets input hint to fine-tune input methods behavior */ + void (*bidi_direction_set) (Ecore_IMF_Context *ctx, Ecore_IMF_BiDi_Direction direction); /**< Set bidirectionality at the cursor position */ }; +/** + * @struct _Ecore_IMF_Context_Info + * @brief A IMF structure containing context information. + */ struct _Ecore_IMF_Context_Info { const char *id; /* ID */ @@ -597,6 +699,15 @@ EAPI int ecore_imf_init(void); */ EAPI int ecore_imf_shutdown(void); +/** + * Register an Ecore_IMF module. + * + * @param info An Ecore_IMF_Context_Info structure + * @param imf_module_create A function to call at the creation + * @param imf_module_exit A function to call when exiting + * + * @ingroup Ecore_IMF_Lib_Group + */ EAPI void ecore_imf_module_register(const Ecore_IMF_Context_Info *info, Ecore_IMF_Context *(*imf_module_create)(void), Ecore_IMF_Context *(*imf_module_exit)(void)); /** @@ -619,6 +730,18 @@ EAPI Eina_Bool ecore_imf_input_panel_hide(void); * @ingroup Ecore_IMF_Context_Group */ EAPI Eina_List *ecore_imf_context_available_ids_get(void); + +/** + * Get the list of the available Input Method Context ids by canvas type. + * + * Note that the caller is responsible for freeing the Eina_List + * when finished with it. There is no need to finish the list strings. + * + * @param canvas_type A string containing the canvas type. + * @return Return an Eina_List of strings; + * on failure it returns NULL. + * @ingroup Ecore_IMF_Context_Group + */ EAPI Eina_List *ecore_imf_context_available_ids_by_canvas_type_get(const char *canvas_type); /** @@ -631,6 +754,18 @@ EAPI Eina_List *ecore_imf_context_available_ids_by_canvas_typ * @ingroup Ecore_IMF_Context_Group */ EAPI const char *ecore_imf_context_default_id_get(void); + +/** + * Get the id of the default Input Method Context corresponding to a canvas + * type. + * The id may be used to create a new instance of an Input Method + * Context object. + * + * @param canvas_type A string containing the canvas type. + * @return Return a string containing the id of the default Input + * Method Context; on failure it returns NULL. + * @ingroup Ecore_IMF_Context_Group + */ EAPI const char *ecore_imf_context_default_id_by_canvas_type_get(const char *canvas_type); /** From 42a7d9b71c05153c90c4224996bdabcd1d9defab Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Wed, 15 Oct 2014 10:20:13 +0200 Subject: [PATCH 22/55] ecore_file: remove ecore_file_ls_iterator function from header. It has no implementation in the ecore_file.c file. This has been forgotten in commit d4059c7 when moving this function to Eina library. --- src/lib/ecore_file/Ecore_File.h | 1 - 1 file changed, 1 deletion(-) diff --git a/src/lib/ecore_file/Ecore_File.h b/src/lib/ecore_file/Ecore_File.h index 530b3cd028..806ad87f84 100644 --- a/src/lib/ecore_file/Ecore_File.h +++ b/src/lib/ecore_file/Ecore_File.h @@ -140,7 +140,6 @@ EAPI Eina_Bool ecore_file_can_write (const char *file); EAPI Eina_Bool ecore_file_can_exec (const char *file); EAPI char *ecore_file_readlink (const char *link); EAPI Eina_List *ecore_file_ls (const char *dir); -EAPI Eina_Iterator *ecore_file_ls_iterator (const char *dir); EAPI char *ecore_file_app_exe_get (const char *app); EAPI char *ecore_file_escape_name (const char *filename); EAPI char *ecore_file_strip_ext (const char *file); From 6a9cfbcfef8a1b947de3266931cdec6bfae38cbc Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Wed, 15 Oct 2014 17:59:55 +0200 Subject: [PATCH 23/55] ecore: update the doxygen groups to compile forgotten parts of the API. Some parts of the API documentation where not compiled at all by doxygen because of missing '@{' and '@}' tags. This commit adds the missing tags in Ecore_Getopt.h, Ecore_Con_Eet.h, and Ecore_IMF.h headers. --- src/lib/ecore/Ecore_Getopt.h | 13 +++++++++++-- src/lib/ecore_con/Ecore_Con_Eet.h | 10 ++++++++-- src/lib/ecore_imf/Ecore_IMF.h | 2 ++ 3 files changed, 21 insertions(+), 4 deletions(-) diff --git a/src/lib/ecore/Ecore_Getopt.h b/src/lib/ecore/Ecore_Getopt.h index 439e021782..a20cc98e02 100644 --- a/src/lib/ecore/Ecore_Getopt.h +++ b/src/lib/ecore/Ecore_Getopt.h @@ -31,8 +31,10 @@ #endif /* ! _WIN32 */ /** - * @file Ecore_Getopt.h - * @brief Contains powerful getopt replacement. + * @defgroup Ecore_Getopt_Group Ecore Getopt + * @ingroup Ecore + * + * This group contains powerful getopt replacement. * * This replacement handles both short (-X) or long options (--ABC) * options, with various actions supported, like storing one value and @@ -46,6 +48,8 @@ * Values will be stored elsewhere indicated by an array of pointers * to values, it is given in separate to parser description so you can * use multiple values with the same parser. + * + * @{ */ #ifdef __cplusplus @@ -1206,4 +1210,9 @@ EAPI Eina_Bool ecore_getopt_callback_size_parse(const Ecore_Getopt *parser, con #ifdef __cplusplus } #endif + +/** + * @} + */ + #endif /* _ECORE_GETOPT_H */ diff --git a/src/lib/ecore_con/Ecore_Con_Eet.h b/src/lib/ecore_con/Ecore_Con_Eet.h index 95373c46b8..a6c52bd328 100644 --- a/src/lib/ecore_con/Ecore_Con_Eet.h +++ b/src/lib/ecore_con/Ecore_Con_Eet.h @@ -32,13 +32,15 @@ #endif /** - * @defgroup Ecore_Con_Eet_Group Ecore_Con_Eet - Eet connection functions - * @ingroup Ecore + * @defgroup Ecore_Con_Eet_Group Eet connection functions + * @ingroup Ecore_Con_Group * * The Ecore Connection Eet library ( @c Ecore_Con_Eet) adds @c Eet data * serialization features to Ecore Connection objects. Its main aim is to * provide a way to send @c Eet data streams to another program through sockets * using @c Ecore_Con objects. + * + * @{ */ typedef struct _Ecore_Con_Eet Ecore_Con_Eet; @@ -275,4 +277,8 @@ EAPI void ecore_con_eet_send(Ecore_Con_Reply *reply, const char *protocol_name, */ EAPI void ecore_con_eet_raw_send(Ecore_Con_Reply *reply, const char *protocol_name, const char *section, void *value, unsigned int length); +/** + * @} + */ + #endif diff --git a/src/lib/ecore_imf/Ecore_IMF.h b/src/lib/ecore_imf/Ecore_IMF.h index 374c0904a1..5618f3130d 100644 --- a/src/lib/ecore_imf/Ecore_IMF.h +++ b/src/lib/ecore_imf/Ecore_IMF.h @@ -1805,6 +1805,7 @@ EAPI Eina_Bool ecore_imf_context_input_panel_show_on_demand_ /** * @brief Sets the bidirectionality at the current cursor position. * + * @ingroup Ecore_IMF_Context_Group * @since 1.12.0 * * @param[in] ctx An #Ecore_IMF_Context @@ -1815,6 +1816,7 @@ EAPI void ecore_imf_context_bidi_direction_set(Ecore_IM /** * @brief Gets the bidirectionality at the current cursor position. * + * @ingroup Ecore_IMF_Context_Group * @since 1.12.0 * * @param[in] ctx An #Ecore_IMF_Context From ab9691be44064cb6b6e5fcb8cc82d0aa99a6885d Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Wed, 15 Oct 2014 18:01:07 +0200 Subject: [PATCH 24/55] ecore: update Ecore documentation main page. Add missing groups and remove groups that are already in subgroups in order to have a nicer Ecore main page in the documentation. --- src/lib/ecore/Ecore.h | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/src/lib/ecore/Ecore.h b/src/lib/ecore/Ecore.h index bef9db8d28..46bb9673af 100644 --- a/src/lib/ecore/Ecore.h +++ b/src/lib/ecore/Ecore.h @@ -23,15 +23,22 @@ it can be found in @ref Ecore_Main_Loop_Page. The Ecore library provides the following modules: + @li @ref Ecore_Init_Group + @li @ref Ecore_Getopt_Group @li @ref Ecore_Main_Loop_Group + @li @ref Ecore_System_Events + @li @ref Ecore_Time_Group + @li @ref Ecore_Thread_Group + @li @ref Ecore_Pipe_Group + @li @ref Ecore_Application_Group + @li @ref Ecore_Throttle_Group + @li @ref Ecore_Job_Group @li @ref Ecore_File_Group @li @ref Ecore_Con_Group @li @ref Ecore_Evas_Group @li @ref Ecore_FB_Group + @li @ref Ecore_Input_Group @li @ref Ecore_IMF_Lib_Group - @li @ref Ecore_IMF_Context_Group - @li @ref Ecore_IMF_Context_Module_Group - @li @ref Ecore_IMF_Evas_Group @li @link Ecore_Ipc.h Ecore_IPC - Inter Process Communication functions. @endlink @li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink @li @ref Ecore_Win32_Group @@ -80,6 +87,9 @@ @li @ref Ecore_FD_Handler_Group @li @ref Ecore_Event_Group @li @ref Ecore_Exe_Group + @li @ref Ecore_Animator_Group + @li @ref Ecore_Poller_Group + @section ecore_main_intro_example Introductory Examples From 4c0b383dc4385a0acd1c8bcb4665a861990c926c Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Thu, 16 Oct 2014 13:20:43 +0200 Subject: [PATCH 25/55] ecore_input: update missing Ecore_Input.h API documentation. --- src/lib/ecore_input/Ecore_Input.h | 271 +++++++++++++++++++----------- 1 file changed, 175 insertions(+), 96 deletions(-) diff --git a/src/lib/ecore_input/Ecore_Input.h b/src/lib/ecore_input/Ecore_Input.h index 46e3e6ea87..f9f781a7fc 100644 --- a/src/lib/ecore_input/Ecore_Input.h +++ b/src/lib/ecore_input/Ecore_Input.h @@ -39,6 +39,12 @@ extern "C" { #endif +/** + * @defgroup Ecore_Input_Group Ecore Input + * @ingroup Ecore_Group + * + *@{ + */ EAPI extern int ECORE_EVENT_KEY_DOWN; EAPI extern int ECORE_EVENT_KEY_UP; EAPI extern int ECORE_EVENT_MOUSE_BUTTON_DOWN; @@ -72,7 +78,11 @@ extern "C" { typedef struct _Ecore_Event_Mouse_Move Ecore_Event_Mouse_Move; typedef struct _Ecore_Event_Mouse_IO Ecore_Event_Mouse_IO; typedef struct _Ecore_Event_Modifiers Ecore_Event_Modifiers; - + + /** + * @typedef Ecore_Event_Modifier + * An enum of modifier events. + */ typedef enum _Ecore_Event_Modifier { ECORE_NONE, @@ -86,18 +96,30 @@ extern "C" { ECORE_LAST } Ecore_Event_Modifier; + /** + * @typedef Ecore_Event_Press + * An enum of press events. + */ typedef enum _Ecore_Event_Press { ECORE_DOWN, ECORE_UP } Ecore_Event_Press; + /** + * @typedef Ecore_Event_IO + * An enum of Input/Output events. + */ typedef enum _Ecore_Event_IO { ECORE_IN, ECORE_OUT } Ecore_Event_IO; + /** + * @typedef Ecore_Compose_State + * An enum of Compose states. + */ typedef enum _Ecore_Compose_State { ECORE_COMPOSE_NONE, @@ -105,140 +127,197 @@ extern "C" { ECORE_COMPOSE_DONE } Ecore_Compose_State; + /** + * @struct _Ecore_Event_Key + * Contains information about an Ecore keyboard event. + */ struct _Ecore_Event_Key { - const char *keyname; - const char *key; + const char *keyname; /**< The key name */ + const char *key; /**< The key symbol */ const char *string; - const char *compose; - Ecore_Window window; - Ecore_Window root_window; - Ecore_Window event_window; + const char *compose; /**< final string corresponding to the key symbol composed */ + Ecore_Window window; /**< The main window where event happened */ + Ecore_Window root_window; /**< The root window where event happened */ + Ecore_Window event_window; /**< The child window where event happened */ - unsigned int timestamp; - unsigned int modifiers; + unsigned int timestamp; /**< Time when the event occurred */ + unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ - int same_screen; + int same_screen; /**< same screen flag */ unsigned int keycode; /**< Key scan code numeric value @since 1.10 */ void *data; /**< User data associated with an Ecore_Event_Key @since 1.10 */ }; + /** + * @struct _Ecore_Event_Mouse_Button + * Contains information about an Ecore mouse button event. + */ struct _Ecore_Event_Mouse_Button { - Ecore_Window window; - Ecore_Window root_window; - Ecore_Window event_window; + Ecore_Window window; /**< The main window where event happened */ + Ecore_Window root_window; /**< The root window where event happened */ + Ecore_Window event_window; /**< The child window where event happened */ + + unsigned int timestamp; /**< Time when the event occurred */ + unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ + unsigned int buttons; /**< The button that was used */ + unsigned int double_click; /**< Double click event */ + unsigned int triple_click; /**< Triple click event */ + int same_screen; /**< Same screen flag */ - unsigned int timestamp; - unsigned int modifiers; - unsigned int buttons; - unsigned int double_click; - unsigned int triple_click; - int same_screen; - - int x; - int y; + int x; /**< x coordinate relative to window where event happened */ + int y; /**< y coordinate relative to window where event happened */ struct { int x; int y; - } root; + } root; /**< Coordinates relative to root window */ struct { - int device; /* 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers) */ - double radius, radius_x, radius_y; /* radius of press point - radius_x and y if its an ellipse (radius is the average of the 2) */ - double pressure; /* pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ - double angle; /* angle relative to perpendicular (0.0 == perpendicular), in degrees */ - double x, y; /* same as x, y root.x, root.y, but with sub-pixel precision, if available */ + int device; /**< 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers) */ + double radius, radius_x, radius_y; /**< radius of press point - radius_x and y if its an ellipse (radius is the average of the 2) */ + double pressure; /**< pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ + double angle; /**< angle relative to perpendicular (0.0 == perpendicular), in degrees */ + double x, y; /**< same as x, y, but with sub-pixel precision, if available */ struct { double x, y; - } root; + } root; /**< same as root.x, root.y, but with sub-pixel precision, if available */ } multi; }; - - struct _Ecore_Event_Mouse_Wheel - { - Ecore_Window window; - Ecore_Window root_window; - Ecore_Window event_window; - - unsigned int timestamp; - unsigned int modifiers; - - int same_screen; - int direction; - int z; - - int x; - int y; - struct { - int x; - int y; - } root; - }; - - struct _Ecore_Event_Mouse_Move - { - Ecore_Window window; - Ecore_Window root_window; - Ecore_Window event_window; - - unsigned int timestamp; - unsigned int modifiers; - - int same_screen; - - int x; - int y; - struct { - int x; - int y; - } root; - - struct { - int device; /* 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers) */ - double radius, radius_x, radius_y; /* radius of press point - radius_x and y if its an ellipse (radius is the average of the 2) */ - double pressure; /* pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ - double angle; /* angle relative to perpendicular (0.0 == perpendicular), in degrees */ - double x, y; /* same as x, y root.x, root.y, but with sub-pixel precision, if available */ - struct { - double x, y; - } root; - } multi; - }; - - struct _Ecore_Event_Mouse_IO - { - Ecore_Window window; - Ecore_Window event_window; - - unsigned int timestamp; - unsigned int modifiers; - - int x; - int y; - }; + /** + * @struct _Ecore_Event_Mouse_Wheel + * Contains information about an Ecore mouse wheel event. + */ + struct _Ecore_Event_Mouse_Wheel + { + Ecore_Window window; /**< The main window where event happened */ + Ecore_Window root_window; /**< The root window where event happened */ + Ecore_Window event_window; /**< The child window where event happened */ + + unsigned int timestamp; /**< Time when the event occurred */ + unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ + + int same_screen; /**< Same screen flag */ + int direction; /**< Orientation of the wheel (horizontal/vertical) */ + int z; /**< Value of the wheel event (+1/-1) */ + + int x; /**< x coordinate relative to window where event happened */ + int y; /**< y coordinate relative to window where event happened */ + struct { + int x; + int y; + } root; /**< Coordinates relative to root window */ + }; + + /** + * @struct _Ecore_Event_Mouse_Move + * Contains information about an Ecore mouse move event. + */ + struct _Ecore_Event_Mouse_Move + { + Ecore_Window window; /**< The main window where event happened */ + Ecore_Window root_window; /**< The root window where event happened */ + Ecore_Window event_window; /**< The child window where event happened */ + + unsigned int timestamp; /**< Time when the event occurred */ + unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ + + int same_screen; /**< Same screen flag */ + + int x; /**< x coordinate relative to window where event happened */ + int y; /**< y coordinate relative to window where event happened */ + struct { + int x; + int y; + } root; /**< Coordinates relative to root window */ + + struct { + int device; /**< 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers) */ + double radius, radius_x, radius_y; /**< radius of press point - radius_x and y if its an ellipse (radius is the average of the 2) */ + double pressure; /**< pressure - 1.0 == normal, > 1.0 == more, 0.0 == none */ + double angle; /**< angle relative to perpendicular (0.0 == perpendicular), in degrees */ + double x, y; /**< same as x, y root.x, root.y, but with sub-pixel precision, if available */ + struct { + double x, y; + } root; + } multi; + }; + + /** + * @struct _Ecore_Event_Mouse_IO + * Contains information about an Ecore mouse input/output event. + */ + struct _Ecore_Event_Mouse_IO + { + Ecore_Window window; /**< The main window where event happened */ + Ecore_Window event_window; /**< The child window where event happened */ + + unsigned int timestamp; /**< Time when the event occurred */ + unsigned int modifiers; /**< The combination of modifiers key (SHIT,CTRL,ALT,..)*/ + + int x /**< x coordinate relative to window where event happened */ + int y /**< y coordinate relative to window where event happened */ + }; + + /** + * @struct _Ecore_Event_Modifiers + * Contains information about an Ecore event modifier. + */ struct _Ecore_Event_Modifiers { unsigned int size; unsigned int array[ECORE_LAST]; }; - + + /** + * Initialises the Ecore Event system. + */ EAPI int ecore_event_init(void); + /** + * Shutdowns the Ecore Event system. + */ EAPI int ecore_event_shutdown(void); - + + /** + * Return the Ecore modifier event integer associated to a + * Ecore_Event_Modifier modifier event. + * + * @param modifier A Ecore_Event_Modifier event. + * @return A event_modifier integer that matches with the provided modifier + * event. + */ EAPI unsigned int ecore_event_modifier_mask(Ecore_Event_Modifier modifier); + + /** + * Update a Ecore_Event_Modifiers array with "key" modifier. + * + * @param key A string describing a modifier key. + * @param modifiers A Ecore_Event_Modifiers structure. + * @param inc The value to increment in the modifiers array. + * + * @return ECORE_NONE if the key does not match with an existing one, else + * the corresponding Ecore_Event_Modifier. + */ EAPI Ecore_Event_Modifier ecore_event_update_modifier(const char *key, Ecore_Event_Modifiers *modifiers, int inc); /** - * @since 1.7 + * Handle a sequence of key symbols to make a final compose string. + * + * The final compose string seqstr_ret is allocated in this function and + * thus shall be freed when not needed anymore. + * + * @param seq The sequence of key symbols in a Eina_List. + * @param seqstr_ret The final compose string. + * @return The status of the composition. */ EAPI Ecore_Compose_State ecore_compose_get(const Eina_List *seq, char **seqstr_ret); - + #ifdef __cplusplus } #endif +/** @} */ #endif From 5bb70347741f4ff5641377eb9d6d1a9d22e1488a Mon Sep 17 00:00:00 2001 From: Philippe Caseiro Date: Thu, 16 Oct 2014 16:38:31 +0200 Subject: [PATCH 26/55] eet: update callback API documentation. Adding some documentation on callbacks typedefs for : - Eet_Descriptor - Eet_Dump --- src/lib/eet/Eet.h | 174 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 168 insertions(+), 6 deletions(-) diff --git a/src/lib/eet/Eet.h b/src/lib/eet/Eet.h index 0fdad3976a..b75653fe29 100644 --- a/src/lib/eet/Eet.h +++ b/src/lib/eet/Eet.h @@ -137,7 +137,15 @@ extern "C" { * */ +/** + * @def EET_VERSION_MAJOR + * The major number of eet version + */ #define EET_VERSION_MAJOR EFL_VERSION_MAJOR +/** + * @def EET_VERSION_MINOR + * The minor number of eet version + */ #define EET_VERSION_MINOR EFL_VERSION_MINOR /** * @typedef Eet_Version @@ -210,7 +218,7 @@ typedef enum _Eet_Error /** * @} */ - + /** * @defgroup Eet_Compression Eet Compression Levels * @ingroup Eet @@ -233,14 +241,14 @@ typedef enum _Eet_Compression EET_COMPRESSION_HI = 9, /**< Slow but high compression level (Zlib) @since 1.7 */ EET_COMPRESSION_VERYFAST = 10, /**< Very fast, but lower compression ratio (LZ4HC) @since 1.7 */ EET_COMPRESSION_SUPERFAST = 11, /**< Very fast, but lower compression ratio (faster to compress than EET_COMPRESSION_VERYFAST) (LZ4) @since 1.7 */ - + EET_COMPRESSION_LOW2 = 3, /**< Space filler for compatibility. Don't use it @since 1.7 */ EET_COMPRESSION_MED1 = 4, /**< Space filler for compatibility. Don't use it @since 1.7 */ EET_COMPRESSION_MED2 = 5, /**< Space filler for compatibility. Don't use it @since 1.7 */ EET_COMPRESSION_HI1 = 7, /**< Space filler for compatibility. Don't use it @since 1.7 */ EET_COMPRESSION_HI2 = 8 /**< Space filler for compatibility. Don't use it @since 1.7 */ } Eet_Compression; /**< Eet compression modes @since 1.7 */ - + /** * @} */ @@ -1457,6 +1465,7 @@ eet_data_image_header_read_cipher(Eet_File *ef, * * @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. * @param cspaces Returned pointer by Eet to a list of possible decoding colorspace finished by @c EET_COLORSPACE_ARGB8888. If @c NULL, only EET_COLORSPACE_ARGB8888 is supported. * @return 1 on successful get, 0 otherwise. * @@ -1591,7 +1600,7 @@ eet_data_image_read_to_surface_cipher(Eet_File *ef, * @param row_stride The length of a pixels line in the destination surface. * @param cspace The color space of the pixels bsurface. * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. + * @param comp A pointer to the int to hold the compression amount. * @param quality A pointer to the int to hold the quality amount. * @param lossy A pointer to the int to hold the lossiness flag. * @return 1 on success, 0 otherwise. @@ -1653,7 +1662,7 @@ eet_data_image_read_to_cspace_surface_cipher(Eet_File *ef, * @param row_stride The length of a pixels line in the destination surface. * @param cspace The color space of the pixel surface * @param alpha A pointer to the int to hold the alpha flag. - * @param compress A pointer to the int to hold the compression amount. + * @param comp A pointer to the int to hold the compression amount. * @param quality A pointer to the int to hold the quality amount. * @param lossy A pointer to the int to hold the lossiness flag. * @return 1 on success, 0 otherwise. @@ -2606,24 +2615,168 @@ typedef struct _Eet_Data_Descriptor Eet_Data_Descriptor; */ typedef struct _Eet_Data_Descriptor_Class Eet_Data_Descriptor_Class; +/** + * @typedef (*Eet_Descriptor_Hash_Foreach_Callback_Callback) + * + * Callback prototype for Eet_Descriptor_Hash_Foreach_Callback + * @param h the hash + * @param k the key + * @param dt the data + * @param fdt the data passed to the callback + * @return an integer + */ typedef int (*Eet_Descriptor_Hash_Foreach_Callback_Callback)(void *h, const char *k, void *dt, void *fdt); +/** + * @typedef (*Eet_Descriptor_Mem_Alloc_Callback) + * + * Callback prototype for Eet_Descriptor_Mem_Alloc + * @param size is the size of memory to alloc on call of the callback + */ typedef void * (*Eet_Descriptor_Mem_Alloc_Callback)(size_t size); + +/** + * @typedef (*Eet_Descriptor_Mem_Free_Callback) + * + * Callback prototype for Eet_Descriptor_Mem_Alloc + * @param mem must be a pointer to free on call of the callback + */ typedef void (*Eet_Descriptor_Mem_Free_Callback)(void *mem); + +/** + * @typedef (*Eet_Descriptor_Str_Alloc_Callback) + * + * Callback prototype for Eet_Descriptor_Str_Alloc + * @param str must be the string to alloc + * @return have must be an allocated char * for the given string + */ typedef char * (*Eet_Descriptor_Str_Alloc_Callback)(const char *str); + +/** + * @typedef (*Eet_Descriptor_Str_Free_Callback) + * + * Callback prototype for Eet_Descriptor_Str_Free + * @param str must be an allocated string to free + */ typedef void (*Eet_Descriptor_Str_Free_Callback)(const char *str); + +/** + * @typedef (*Eet_Descriptor_List_Next_Callback) + * + * Callback prototype for Eet_Descriptor_List_Next + * @param l must be a pointer to the list + * @return must be a pointer to the list + */ typedef void * (*Eet_Descriptor_List_Next_Callback)(void *l); + +/** + * @typedef (*Eet_Descriptor_List_Append_Callback) + * + * Callback prototype for Eet_Descriptor_List_Append + * @param l must be a pointer to the list + * @param d the data to append to the list + * @return must be a pointer to the list + */ typedef void * (*Eet_Descriptor_List_Append_Callback)(void *l, void *d); + + +/** + * @typedef (*Eet_Descriptor_List_Data_Callback) + * + * Callback prototype for Eet_Descriptor_List_Data + * @param l must be a pointer to the list + * @return must be a pointer to the list + */ typedef void * (*Eet_Descriptor_List_Data_Callback)(void *l); + +/** + * @typedef (*Eet_Descriptor_List_Free_Callback) + * + * Callback prototype for Eet_Descriptor_List_Free + * @param l must be a pointer to the list to free + */ typedef void * (*Eet_Descriptor_List_Free_Callback)(void *l); + +/** + * @typedef (*Eet_Descriptor_Hash_Foreach_Callback) + * + * Callback for Eet_Descriptor_Hash_Foreach + * @param h the hash + * @param func the function callback to call on each iteration + * @param fdt the data to pass to the callbac setted in param func + */ typedef void (*Eet_Descriptor_Hash_Foreach_Callback)(void *h, Eet_Descriptor_Hash_Foreach_Callback_Callback func, void *fdt); + +/** + * @typedef (*Eet_Descriptor_Hash_Add_Callback) + * + * Callback prototype for Eet_Descriptor_Hash_Add + * @param h the hash + * @param k the key + * @param d the data to associate with the 'k' key + */ typedef void * (*Eet_Descriptor_Hash_Add_Callback)(void *h, const char *k, void *d); + +/** + * @typedef (*Eet_Descriptor_Hash_Free_Callback) + * + * Callback prototype for Eet_Descriptor_Hash_Free + * @param h the hash to free + */ typedef void (*Eet_Descriptor_Hash_Free_Callback)(void *h); + +/** + * @typedef (*Eet_Descriptor_Str_Alloc_Callback) + * + * Callback prototype for Eet_Descriptor_Str_Alloc + * @param str the string to allocate + * @return an allocated pointer to the string + */ typedef char * (*Eet_Descriptor_Str_Direct_Alloc_Callback)(const char *str); + +/** + * @typedef (*Eet_Descriptor_Str_Free_Callback) + * + * Callback prototype for Eet_Descriptor_Str_Free + * @param str the string to free + */ typedef void (*Eet_Descriptor_Str_Direct_Free_Callback)(const char *str); + + +/** + * @typedef (*Eet_Descriptor_Type_Get_Callback) + * + * Callback prototype for Eet_Descriptor_Type_Get + * @param data data to pass to the callback + * @param unknow Eina_Bool __FIXME__ + */ typedef const char * (*Eet_Descriptor_Type_Get_Callback)(const void *data, Eina_Bool *unknow); + +/** + * @typedef (*Eet_Descriptor_Type_Set_Callback) + * + * Callback prototype for Eet_Descriptor_Type_Set + * @param type the type to set + * @param data to pass to the callback + * @param unknow Eina_Bool __FIXME__ + */ typedef Eina_Bool (*Eet_Descriptor_Type_Set_Callback)(const char *type, void *data, Eina_Bool unknow); + + +/** + * @typedef (*Eet_Descriptor_Array_Alloc_Callback) + * + * Callback prototype for Eet_Descriptor_Array_Alloc + * @param size The size of the array + */ typedef void * (*Eet_Descriptor_Array_Alloc_Callback)(size_t size); + +/** + * @typedef (*Eet_Descriptor_Array_Free_Callback) + * + * Callback prototype for Eet_Descriptor_Array_Free + * @param size The size of the array + */ typedef void (*Eet_Descriptor_Array_Free_Callback)(void *mem); /** * @struct _Eet_Data_Descriptor_Class @@ -3006,6 +3159,15 @@ eet_data_write(Eet_File *ef, const void *data, int compress); +/** + * @typedef Eet_Data_Descriptor_Class + * + * Callback protoype for Eet_Dump + * + * @param data to passe to the callback + * @param str the string to dump + * + */ typedef void (*Eet_Dump_Callback)(void *data, const char *str); /** @@ -4260,7 +4422,7 @@ EAPI Eet_Node * eet_node_parent_get(Eet_Node *node); /** - * TODO FIX ME + * @brief Append a "list" node TODO FIX ME * @ingroup Eet_Node_Group */ EAPI void From c03569e6a7d637d0e65e20ac4d669103eb1484f7 Mon Sep 17 00:00:00 2001 From: Philippe Caseiro Date: Fri, 17 Oct 2014 09:52:30 +0200 Subject: [PATCH 27/55] eet: update callback API documentation Adding some documentation on callbacks typedefs for : - Eet_Node_Walk --- src/lib/eet/Eet.h | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/src/lib/eet/Eet.h b/src/lib/eet/Eet.h index b75653fe29..25029396ba 100644 --- a/src/lib/eet/Eet.h +++ b/src/lib/eet/Eet.h @@ -3864,7 +3864,8 @@ eet_data_read_cipher(Eet_File *ef, * @param edd The data descriptor handle to use when decoding. * @param name The key the data is stored under in the eet file. * @param cipher_key The key to use as cipher. - * @param buffer Buffer + * @param buffer Buffer. + * @param buffer_size The buffer size. * @return A pointer to buffer if successful and NULL on error. * * This function decodes a data structure stored in an eet file, returning @@ -4530,9 +4531,37 @@ eet_data_node_write_cipher(Eet_File *ef, */ typedef struct _Eet_Node_Walk Eet_Node_Walk; +/** + * @typedef (*Eet_Node_Walk_Struct_Alloc_Callback) + * + * Callback prototype for Eet_Node_Walk_Struct_Alloc + * @param type The allocation type + * @param user_data the data passed by the user to the callback + */ typedef void * (*Eet_Node_Walk_Struct_Alloc_Callback)(const char *type, void *user_data); + +/** + * @typedef (*Eet_Node_Walk_Struct_Add_Callback) + * + * Callback prototype for Eet_Node_Walk_Struct_Add + * @param parent The parent node + * @param name the name for the new node + * @param child the child node + * @param user_data the data passed by the user to the callback + */ typedef void (*Eet_Node_Walk_Struct_Add_Callback)(void *parent, const char *name, void *child, void *user_data); + +/** + * @typedef (*Eet_Node_Walk_Array_Callback) + * + * Callback prototype for Eet_Node_Walk_Array + * @param variable EINA_TRUE or EINA_FALSE + * @param name a name + * @param count a counter + * @param user_data the data passed by the user to the callback + */ typedef void * (*Eet_Node_Walk_Array_Callback)(Eina_Bool variable, const char *name, int count, void *user_data); + typedef void (*Eet_Node_Walk_Insert_Callback)(void *array, int index, void *child, void *user_data); typedef void * (*Eet_Node_Walk_List_Callback)(const char *name, void *user_data); typedef void (*Eet_Node_Walk_Append_Callback)(void *list, void *child, void *user_data); From fe72de9cc020f7fe4fe0cb8404169bbda6563d11 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 17 Oct 2014 10:58:02 +0200 Subject: [PATCH 28/55] evas: more documentation of Evas_Common. Fix inline comments --- src/lib/evas/Evas_Common.h | 113 ++++++++++++++++++++++--------------- 1 file changed, 69 insertions(+), 44 deletions(-) diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h index 95f788652e..bc9a62eedd 100644 --- a/src/lib/evas/Evas_Common.h +++ b/src/lib/evas/Evas_Common.h @@ -29,10 +29,10 @@ typedef struct _Evas_Version { - int major; /** < major (binary or source incompatible changes) */ - int minor; /** < minor (new features, bugfixes, major improvements version) */ - int micro; /** < micro (bugfix, internal improvements, no new features version) */ - int revision; /** < git revision (0 if a proper release or the git revision number Evas is built from) */ + int major; /**< major (binary or source incompatible changes) */ + int minor; /**< minor (new features, bugfixes, major improvements version) */ + int micro; /**< micro (bugfix, internal improvements, no new features version) */ + int revision; /**< git revision (0 if a proper release or the git revision number Evas is built from) */ } Evas_Version; EAPI extern Evas_Version * evas_version; @@ -219,8 +219,8 @@ typedef struct _Evas_Point Evas_Point; /**< integer point */ typedef struct _Evas_Coord_Point Evas_Coord_Point; /**< Evas_Coord point */ typedef struct _Evas_Coord_Precision_Point Evas_Coord_Precision_Point; /**< Evas_Coord point with sub-pixel precision */ -typedef struct _Evas_Coord_Size Evas_Coord_Size; /** Date: Fri, 17 Oct 2014 10:59:26 +0200 Subject: [PATCH 29/55] evas: add documentation for enums in Evas_Gl.h. --- src/lib/evas/Evas_GL.h | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/lib/evas/Evas_GL.h b/src/lib/evas/Evas_GL.h index 5f2a8d1f71..99d9dd075a 100644 --- a/src/lib/evas/Evas_GL.h +++ b/src/lib/evas/Evas_GL.h @@ -402,10 +402,10 @@ typedef enum _Evas_GL_Color_Format typedef enum _Evas_GL_Depth_Bits { EVAS_GL_DEPTH_NONE = 0, - EVAS_GL_DEPTH_BIT_8 = 1, - EVAS_GL_DEPTH_BIT_16 = 2, - EVAS_GL_DEPTH_BIT_24 = 3, - EVAS_GL_DEPTH_BIT_32 = 4 + EVAS_GL_DEPTH_BIT_8 = 1, /**< 8 bits precision surface depth */ + EVAS_GL_DEPTH_BIT_16 = 2, /**< 16 bits precision surface depth */ + EVAS_GL_DEPTH_BIT_24 = 3, /**< 24 bits precision surface depth */ + EVAS_GL_DEPTH_BIT_32 = 4 /**< 32 bits precision surface depth */ } Evas_GL_Depth_Bits; /** @@ -414,11 +414,11 @@ typedef enum _Evas_GL_Depth_Bits typedef enum _Evas_GL_Stencil_Bits { EVAS_GL_STENCIL_NONE = 0, - EVAS_GL_STENCIL_BIT_1 = 1, - EVAS_GL_STENCIL_BIT_2 = 2, - EVAS_GL_STENCIL_BIT_4 = 3, - EVAS_GL_STENCIL_BIT_8 = 4, - EVAS_GL_STENCIL_BIT_16 = 5 + EVAS_GL_STENCIL_BIT_1 = 1, /**< 1 bit precision for stencil buffer */ + EVAS_GL_STENCIL_BIT_2 = 2, /**< 2 bits precision for stencil buffer */ + EVAS_GL_STENCIL_BIT_4 = 3, /**< 4 bits precision for stencil buffer */ + EVAS_GL_STENCIL_BIT_8 = 4, /**< 8 bits precision for stencil buffer */ + EVAS_GL_STENCIL_BIT_16 = 5 /**< 16 bits precision for stencil buffer */ } Evas_GL_Stencil_Bits; /** From 91c4a14cc596537a2934759cb3872ef491b1d71b Mon Sep 17 00:00:00 2001 From: Philippe Caseiro Date: Fri, 17 Oct 2014 14:31:03 +0200 Subject: [PATCH 30/55] edje: update typedef and callbacks documentation. --- src/lib/edje/Edje_Common.h | 239 +++++++++++++++++++++++++------------ 1 file changed, 160 insertions(+), 79 deletions(-) diff --git a/src/lib/edje/Edje_Common.h b/src/lib/edje/Edje_Common.h index 918553eea8..d563972506 100644 --- a/src/lib/edje/Edje_Common.h +++ b/src/lib/edje/Edje_Common.h @@ -8,10 +8,10 @@ */ typedef struct _Edje_Version { - int major; - int minor; - int micro; - int revision; + int major; /**< The major number of Edje version. */ + int minor; /**< The minor number of Edje version. */ + int micro; /**< The micro number of Edje version. */ + int revision; /**< The revision of Edje version) */ } Edje_Version; EAPI extern Edje_Version *edje_version; @@ -989,6 +989,10 @@ typedef enum _Edje_Input_Panel_Return_Key_Type EDJE_INPUT_PANEL_RETURN_KEY_TYPE_SIGNIN /**< Sign-in @since 1.8 */ } Edje_Input_Panel_Return_Key_Type; +/** + * @typedef Edje_Input_Panel_Layout + * @brief Edje input panel layout + */ typedef enum _Edje_Input_Panel_Layout { EDJE_INPUT_PANEL_LAYOUT_NORMAL, /**< Default layout */ @@ -1007,6 +1011,10 @@ typedef enum _Edje_Input_Panel_Layout EDJE_INPUT_PANEL_LAYOUT_EMOTICON /**< Emoticon layout @since 1.10 */ } Edje_Input_Panel_Layout; +/* + * @typedef Edje_Input_Hints + * @brief Edje input hints + */ typedef enum { EDJE_INPUT_HINT_NONE = 0, /**< No active hints @since 1.12 */ @@ -1035,8 +1043,33 @@ enum EDJE_INPUT_PANEL_LAYOUT_PASSWORD_VARIATION_NUMBERONLY /**< The password layout to allow only number @since 1.12 */ }; +/** + * @typedef (*Edje_Text_Filter_Cb) + * @brief Callback prototype for Edje_Text_Filter + * @param obj The Evas_Object to filter. + * @param type The filter type. + * @param text The text of the filter. + */ typedef void (*Edje_Text_Filter_Cb) (void *data, Evas_Object *obj, const char *part, Edje_Text_Filter_Type type, char **text); + +/** + * @typedef (*Edje_Markup_Filter_Cb) + * @brief Callback prototype for Edje_Text_Filter + * @param obj The Evas_Object to filter. + * @param part Edje part name. + * @param text The text of the filter. + */ typedef void (*Edje_Markup_Filter_Cb) (void *data, Evas_Object *obj, const char *part, char **text); + +/** + * @typedef (*Edje_Item_Provider_Cb) + * @brief Callback prototype for Edje_Item_Provider + * @param data some data provided by user + * @param obj The Evas_Object to filter. + * @param part Edje part name + * @param item Item of container + * @return must be an Evas_Object. + */ typedef Evas_Object *(*Edje_Item_Provider_Cb) (void *data, Evas_Object *obj, const char *part, const char *item); /** @@ -1126,6 +1159,8 @@ EAPI void edje_password_show_last_timeout_set(double password_show_last_timeout) * * @note unlike Evas, Edje colors are @b not pre-multiplied. That is, * half-transparent white is 255 255 255 128. + * + * @return Eina_Bool, EINA_TRUE on success and EINA_FALSE on failure. */ EAPI Eina_Bool edje_color_class_set (const char *color_class, int r, int g, int b, int a, int r2, int g2, int b2, int a2, int r3, int g3, int b3, int a3); @@ -1216,22 +1251,28 @@ EAPI Eina_List *edje_color_class_list (void); * @{ */ +/** + * @typedef Edje_Part_Type + * + * All possible "part" types in Edje + */ typedef enum _Edje_Part_Type { - EDJE_PART_TYPE_NONE = 0, - EDJE_PART_TYPE_RECTANGLE = 1, - EDJE_PART_TYPE_TEXT = 2, - EDJE_PART_TYPE_IMAGE = 3, - EDJE_PART_TYPE_SWALLOW = 4, - EDJE_PART_TYPE_TEXTBLOCK = 5, - EDJE_PART_TYPE_GRADIENT = 6, - EDJE_PART_TYPE_GROUP = 7, - EDJE_PART_TYPE_BOX = 8, - EDJE_PART_TYPE_TABLE = 9, - EDJE_PART_TYPE_EXTERNAL = 10, - EDJE_PART_TYPE_PROXY = 11, - EDJE_PART_TYPE_SPACER = 12, /**< @since 1.7 */ - EDJE_PART_TYPE_LAST = 13 + EDJE_PART_TYPE_NONE = 0, /**< None type value */ + EDJE_PART_TYPE_RECTANGLE = 1, /**< Rectangle type value */ + EDJE_PART_TYPE_TEXT = 2, /**< Text type value */ + EDJE_PART_TYPE_IMAGE = 3, /**< Image type value */ + EDJE_PART_TYPE_SWALLOW = 4, /**< Swallow type value */ + EDJE_PART_TYPE_TEXTBLOCK = 5, /**< Text block type value */ + EDJE_PART_TYPE_GRADIENT = 6, /**< Gradient type value */ + EDJE_PART_TYPE_GROUP = 7, /**< Group type value */ + EDJE_PART_TYPE_BOX = 8, /**< Box type value */ + EDJE_PART_TYPE_TABLE = 9, /**< Table type value */ + EDJE_PART_TYPE_EXTERNAL = 10, /**< External type value */ + EDJE_PART_TYPE_PROXY = 11, /**< Proxy type value */ + EDJE_PART_TYPE_SPACER = 12, /**< Spacer type value @since 1.7 */ + EDJE_PART_TYPE_LAST = 13 /**< Last type value */ + } Edje_Part_Type; /** * @} @@ -1261,32 +1302,45 @@ typedef enum _Edje_Part_Type #define EDJE_TEXT_EFFECT_SHADOW_DIRECTION_SET(x, s) \ do { x = ((x) & ~EDJE_TEXT_EFFECT_MASK_SHADOW_DIRECTION) | (s); } while (0) +/** + * @typedef Edje_Text_Effect + * + * All possible text effects in Edje + */ typedef enum _Edje_Text_Effect { - EDJE_TEXT_EFFECT_NONE = 0, - EDJE_TEXT_EFFECT_PLAIN = 1, - EDJE_TEXT_EFFECT_OUTLINE = 2, - EDJE_TEXT_EFFECT_SOFT_OUTLINE = 3, - EDJE_TEXT_EFFECT_SHADOW = 4, - EDJE_TEXT_EFFECT_SOFT_SHADOW = 5, - EDJE_TEXT_EFFECT_OUTLINE_SHADOW = 6, - EDJE_TEXT_EFFECT_OUTLINE_SOFT_SHADOW = 7, - EDJE_TEXT_EFFECT_FAR_SHADOW = 8, - EDJE_TEXT_EFFECT_FAR_SOFT_SHADOW = 9, - EDJE_TEXT_EFFECT_GLOW = 10, + EDJE_TEXT_EFFECT_NONE = 0, /**< None text effect value */ + EDJE_TEXT_EFFECT_PLAIN = 1, /**< Plain text effect value */ + EDJE_TEXT_EFFECT_OUTLINE = 2, /**< Outline text effect value */ + EDJE_TEXT_EFFECT_SOFT_OUTLINE = 3, /**< Soft outline text effect value */ + EDJE_TEXT_EFFECT_SHADOW = 4, /**< Shadown text effect value */ + EDJE_TEXT_EFFECT_SOFT_SHADOW = 5, /**< Soft shadow text effect value */ + EDJE_TEXT_EFFECT_OUTLINE_SHADOW = 6, /**< Outline shadow text effect value */ + EDJE_TEXT_EFFECT_OUTLINE_SOFT_SHADOW = 7, /**< Outline soft shadow text effect value */ + EDJE_TEXT_EFFECT_FAR_SHADOW = 8, /**< Far shadow text effect value */ + EDJE_TEXT_EFFECT_FAR_SOFT_SHADOW = 9, /**< Far soft shadow text effect value */ + EDJE_TEXT_EFFECT_GLOW = 10, /**< Glow text effect value */ - EDJE_TEXT_EFFECT_LAST = 11, + EDJE_TEXT_EFFECT_LAST = 11, /**< Last text effect value */ - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_LEFT = (0x3 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP = (0x5 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), - EDJE_TEXT_EFFECT_SHADOW_DIRECTION_RIGHT = (0x7 << 4) + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM_RIGHT = (0x0 << 4), /**< Bottom right shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM = (0x1 << 4), /**< Bottom shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_BOTTOM_LEFT = (0x2 << 4), /**< Bottom left shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_LEFT = (0x3 << 4), /**< Left shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP_LEFT = (0x4 << 4), /**< Top left shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP = (0x5 << 4), /**< Top shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_TOP_RIGHT = (0x6 << 4), /**< Top right shadow direction value */ + EDJE_TEXT_EFFECT_SHADOW_DIRECTION_RIGHT = (0x7 << 4) /**< right shadow direction value */ } Edje_Text_Effect; +/** + * @typedef (*Edje_Text_Change_Cb) + * + * Callback prototype for Edje_Text_Change + * @param data user provided data to pass to the callback + * @param obj the Evas_Object + * @param The edje part + */ typedef void (*Edje_Text_Change_Cb) (void *data, Evas_Object *obj, const char *part); /** * @} @@ -1328,15 +1382,21 @@ typedef void (*Edje_Text_Change_Cb) (void *data, Evas_Object *obj, c * @{ */ +/** + * @typedef Edje_Cursor + * + * All available cursor states + * + */ typedef enum _Edje_Cursor { - EDJE_CURSOR_MAIN, - EDJE_CURSOR_SELECTION_BEGIN, - EDJE_CURSOR_SELECTION_END, - EDJE_CURSOR_PREEDIT_START, - EDJE_CURSOR_PREEDIT_END, - EDJE_CURSOR_USER, - EDJE_CURSOR_USER_EXTRA, + EDJE_CURSOR_MAIN, /*< Main cursor state */ + EDJE_CURSOR_SELECTION_BEGIN, /*< Selection begin cursor state */ + EDJE_CURSOR_SELECTION_END, /*< Selection end cursor state */ + EDJE_CURSOR_PREEDIT_START, /*< Pre-edit start cursor state */ + EDJE_CURSOR_PREEDIT_END, /*< Pre-edit end cursor starge */ + EDJE_CURSOR_USER, /*< User cursor state */ + EDJE_CURSOR_USER_EXTRA, /*< User extra cursor state */ // more later } Edje_Cursor; @@ -1363,13 +1423,19 @@ typedef enum _Edje_Cursor * @{ */ +/** + * @typedef Edje_Aspect_Control + * + * All Edje aspect control values + * + */ typedef enum _Edje_Aspect_Control { - EDJE_ASPECT_CONTROL_NONE = 0, - EDJE_ASPECT_CONTROL_NEITHER = 1, - EDJE_ASPECT_CONTROL_HORIZONTAL = 2, - EDJE_ASPECT_CONTROL_VERTICAL = 3, - EDJE_ASPECT_CONTROL_BOTH = 4 + EDJE_ASPECT_CONTROL_NONE = 0, /*< None aspect control value */ + EDJE_ASPECT_CONTROL_NEITHER = 1, /*< Neither aspect control value */ + EDJE_ASPECT_CONTROL_HORIZONTAL = 2, /*< Horizontal aspect control value */ + EDJE_ASPECT_CONTROL_VERTICAL = 3, /*< Vertical aspect control value */ + EDJE_ASPECT_CONTROL_BOTH = 4 /*< Both aspect control value */ } Edje_Aspect_Control; /** @@ -1416,12 +1482,17 @@ typedef enum _Edje_Aspect_Control * @{ */ +/** + * @typedef Edje_Drag_Dir + * + * Dragable properties values + */ typedef enum _Edje_Drag_Dir { - EDJE_DRAG_DIR_NONE = 0, - EDJE_DRAG_DIR_X = 1, - EDJE_DRAG_DIR_Y = 2, - EDJE_DRAG_DIR_XY = 3 + EDJE_DRAG_DIR_NONE = 0, /*< Not dragable value */ + EDJE_DRAG_DIR_X = 1, /*< X dragable value */ + EDJE_DRAG_DIR_Y = 2, /*< Y dragable value */ + EDJE_DRAG_DIR_XY = 3 /*< X and Y dragable value */ } Edje_Drag_Dir; /** @@ -1482,11 +1553,17 @@ EAPI void edje_box_layout_register (const char *name, Evas_Object * @{ */ +/** + * @typedef Edje_Object_Table_Homogeneous_Mode + * + * Table homogeneous modes + * + */ typedef enum _Edje_Object_Table_Homogeneous_Mode { - EDJE_OBJECT_TABLE_HOMOGENEOUS_NONE = 0, - EDJE_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1, - EDJE_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2 + EDJE_OBJECT_TABLE_HOMOGENEOUS_NONE = 0, /*< None homogeneous mode */ + EDJE_OBJECT_TABLE_HOMOGENEOUS_TABLE = 1, /*< Table homogeneous mode */ + EDJE_OBJECT_TABLE_HOMOGENEOUS_ITEM = 2 /*< Item homogeneous mode */ } Edje_Object_Table_Homogeneous_Mode; /** @@ -1688,23 +1765,28 @@ EAPI const char *edje_load_error_str (Edje_Load_Error error); * @{ */ +/** + * @typedef Edje_Tween_Mode + * + * Available tween mode for edje animations + */ typedef enum _Edje_Tween_Mode { - EDJE_TWEEN_MODE_NONE = 0, - EDJE_TWEEN_MODE_LINEAR = 1, - EDJE_TWEEN_MODE_SINUSOIDAL = 2, - EDJE_TWEEN_MODE_ACCELERATE = 3, - EDJE_TWEEN_MODE_DECELERATE = 4, - EDJE_TWEEN_MODE_ACCELERATE_FACTOR = 5, - EDJE_TWEEN_MODE_DECELERATE_FACTOR = 6, - EDJE_TWEEN_MODE_SINUSOIDAL_FACTOR = 7, - EDJE_TWEEN_MODE_DIVISOR_INTERP = 8, - EDJE_TWEEN_MODE_BOUNCE = 9, - EDJE_TWEEN_MODE_SPRING = 10, - EDJE_TWEEN_MODE_CUBIC_BEZIER = 11, - EDJE_TWEEN_MODE_LAST = 12, - EDJE_TWEEN_MODE_MASK = 0xff, - EDJE_TWEEN_MODE_OPT_FROM_CURRENT = (1 << 31) + EDJE_TWEEN_MODE_NONE = 0, /*< None tween mode value */ + EDJE_TWEEN_MODE_LINEAR = 1, /*< Linear tween mode value */ + EDJE_TWEEN_MODE_SINUSOIDAL = 2, /*< Sinusoidal tween mode value */ + EDJE_TWEEN_MODE_ACCELERATE = 3, /*< Accelerate tween mode value */ + EDJE_TWEEN_MODE_DECELERATE = 4, /*< Decelerate tween mode value */ + EDJE_TWEEN_MODE_ACCELERATE_FACTOR = 5, /*< Accelerate factor tween mode value */ + EDJE_TWEEN_MODE_DECELERATE_FACTOR = 6, /*< Decelerate factor tween mode value */ + EDJE_TWEEN_MODE_SINUSOIDAL_FACTOR = 7, /*< Sinusoidal factgor tween mode value */ + EDJE_TWEEN_MODE_DIVISOR_INTERP = 8, /*< Divisor iterp tween mode value */ + EDJE_TWEEN_MODE_BOUNCE = 9, /*< Bounce tween mode value */ + EDJE_TWEEN_MODE_SPRING = 10, /*< Spring tween mode value */ + EDJE_TWEEN_MODE_CUBIC_BEZIER = 11, /*< Cubic Bezier tween mode value */ + EDJE_TWEEN_MODE_LAST = 12, /*< Last tween mode value */ + EDJE_TWEEN_MODE_MASK = 0xff, /*< Mask tween mode value */ + EDJE_TWEEN_MODE_OPT_FROM_CURRENT = (1 << 31) /*< Options from current tween mode value */ } Edje_Tween_Mode; typedef enum _Edje_Action_Type @@ -2091,24 +2173,24 @@ typedef enum _Edje_Channel /** * Set the mute state of audio for the process as a whole - * + * * @param channel The channel to set the mute state of * @param mute The mute state - * + * * This sets the mute (no output) state of audio for the given channel. - * + * * @see edje_audio_channel_mute_get() - * + * * @since 1.9 */ EAPI void edje_audio_channel_mute_set(Edje_Channel channel, Eina_Bool mute); /** * Get the mute state of the given channel - * + * * @param channel The channel to get the mute state of * @return The mute state of the channel - * + * * @see edje_audio_channel_mute_set() * * @since 1.9 @@ -2127,4 +2209,3 @@ EAPI const char *edje_object_part_object_name_get(const Evas_Object *obj); /** * @} */ - From 4aa9990c10c7db20102efed3a45ae7955b6e2598 Mon Sep 17 00:00:00 2001 From: Philippe Caseiro Date: Fri, 17 Oct 2014 16:15:22 +0200 Subject: [PATCH 31/55] edje: update typedef documentation. --- src/lib/edje/Edje_Common.h | 138 ++++++++++++++++++++++--------------- 1 file changed, 81 insertions(+), 57 deletions(-) diff --git a/src/lib/edje/Edje_Common.h b/src/lib/edje/Edje_Common.h index d563972506..1051f2e039 100644 --- a/src/lib/edje/Edje_Common.h +++ b/src/lib/edje/Edje_Common.h @@ -669,7 +669,8 @@ EAPI void edje_external_type_array_unregister (const Edje_External_T EAPI unsigned int edje_external_type_abi_version_get (void) EINA_CONST; /** - * Returns an interator of all the registered EXTERNAL types. + * + * @return an iterator of all the registered EXTERNAL types. * * Each item in the iterator is an @c Eina_Hash_Tuple which has the type * of the external in the @c key and #Edje_External_Type as @c data. @@ -823,6 +824,8 @@ EAPI Eina_Bool edje_external_param_choice_get (const Eina_ * @b NOT translated. One must use * Edje_External_Type::translate() to translate those. * + * @param type_name Edje external type name + * * @return the NULL terminated array, or @c NULL if type is unknown or * it does not have any parameter information. * @@ -955,21 +958,36 @@ struct _Edje_Entry_Change_Info */ typedef struct _Edje_Entry_Change_Info Edje_Entry_Change_Info; +/** + * @typedef Edje_Text_Filter_Type + * + * All Edje text filters type values. + */ typedef enum _Edje_Text_Filter_Type { - EDJE_TEXT_FILTER_TEXT = 0, - EDJE_TEXT_FILTER_FORMAT = 1, - EDJE_TEXT_FILTER_MARKUP = 2 + EDJE_TEXT_FILTER_TEXT = 0, /**< Text type filter */ + EDJE_TEXT_FILTER_FORMAT = 1, /**< Format type filter */ + EDJE_TEXT_FILTER_MARKUP = 2 /**< Markup type filter */ } Edje_Text_Filter_Type; +/** + * @typedef Edje_Text_Autocapital_Type + * + * All Text auto capital mode type values + * + */ typedef enum _Edje_Text_Autocapital_Type { - EDJE_TEXT_AUTOCAPITAL_TYPE_NONE, - EDJE_TEXT_AUTOCAPITAL_TYPE_WORD, - EDJE_TEXT_AUTOCAPITAL_TYPE_SENTENCE, - EDJE_TEXT_AUTOCAPITAL_TYPE_ALLCHARACTER + EDJE_TEXT_AUTOCAPITAL_TYPE_NONE, /**< None mode value */ + EDJE_TEXT_AUTOCAPITAL_TYPE_WORD, /**< Word mode value */ + EDJE_TEXT_AUTOCAPITAL_TYPE_SENTENCE, /**< Sentence mode value */ + EDJE_TEXT_AUTOCAPITAL_TYPE_ALLCHARACTER /**< All characters mode value */ } Edje_Text_Autocapital_Type; +/** + * @typedef Edje_Input_Panel_Lang + * + */ typedef enum _Edje_Input_Panel_Lang { EDJE_INPUT_PANEL_LANG_AUTOMATIC, /**< Automatic @since 1.2 */ @@ -991,7 +1009,7 @@ typedef enum _Edje_Input_Panel_Return_Key_Type /** * @typedef Edje_Input_Panel_Layout - * @brief Edje input panel layout + * @brief Edje input panel layout */ typedef enum _Edje_Input_Panel_Layout { @@ -1063,11 +1081,11 @@ typedef void (*Edje_Markup_Filter_Cb) (void *data, Evas_Object *obj, c /** * @typedef (*Edje_Item_Provider_Cb) - * @brief Callback prototype for Edje_Item_Provider - * @param data some data provided by user + * @brief Callback prototype for Edje_Item_Provider + * @param data some data provided by user * @param obj The Evas_Object to filter. - * @param part Edje part name - * @param item Item of container + * @param part Edje part name + * @param item Item of container * @return must be an Evas_Object. */ typedef Evas_Object *(*Edje_Item_Provider_Cb) (void *data, Evas_Object *obj, const char *part, const char *item); @@ -1303,9 +1321,9 @@ typedef enum _Edje_Part_Type do { x = ((x) & ~EDJE_TEXT_EFFECT_MASK_SHADOW_DIRECTION) | (s); } while (0) /** - * @typedef Edje_Text_Effect + * @typedef Edje_Text_Effect * - * All possible text effects in Edje + * All possible text effects in Edje */ typedef enum _Edje_Text_Effect { @@ -1485,7 +1503,7 @@ typedef enum _Edje_Aspect_Control /** * @typedef Edje_Drag_Dir * - * Dragable properties values + * Dragable properties values */ typedef enum _Edje_Drag_Dir { @@ -1772,51 +1790,57 @@ EAPI const char *edje_load_error_str (Edje_Load_Error error); */ typedef enum _Edje_Tween_Mode { - EDJE_TWEEN_MODE_NONE = 0, /*< None tween mode value */ - EDJE_TWEEN_MODE_LINEAR = 1, /*< Linear tween mode value */ - EDJE_TWEEN_MODE_SINUSOIDAL = 2, /*< Sinusoidal tween mode value */ - EDJE_TWEEN_MODE_ACCELERATE = 3, /*< Accelerate tween mode value */ - EDJE_TWEEN_MODE_DECELERATE = 4, /*< Decelerate tween mode value */ - EDJE_TWEEN_MODE_ACCELERATE_FACTOR = 5, /*< Accelerate factor tween mode value */ - EDJE_TWEEN_MODE_DECELERATE_FACTOR = 6, /*< Decelerate factor tween mode value */ - EDJE_TWEEN_MODE_SINUSOIDAL_FACTOR = 7, /*< Sinusoidal factgor tween mode value */ - EDJE_TWEEN_MODE_DIVISOR_INTERP = 8, /*< Divisor iterp tween mode value */ - EDJE_TWEEN_MODE_BOUNCE = 9, /*< Bounce tween mode value */ - EDJE_TWEEN_MODE_SPRING = 10, /*< Spring tween mode value */ - EDJE_TWEEN_MODE_CUBIC_BEZIER = 11, /*< Cubic Bezier tween mode value */ - EDJE_TWEEN_MODE_LAST = 12, /*< Last tween mode value */ - EDJE_TWEEN_MODE_MASK = 0xff, /*< Mask tween mode value */ - EDJE_TWEEN_MODE_OPT_FROM_CURRENT = (1 << 31) /*< Options from current tween mode value */ + EDJE_TWEEN_MODE_NONE = 0, /**< None tween mode value */ + EDJE_TWEEN_MODE_LINEAR = 1, /**< Linear tween mode value */ + EDJE_TWEEN_MODE_SINUSOIDAL = 2, /**< Sinusoidal tween mode value */ + EDJE_TWEEN_MODE_ACCELERATE = 3, /**< Accelerate tween mode value */ + EDJE_TWEEN_MODE_DECELERATE = 4, /**< Decelerate tween mode value */ + EDJE_TWEEN_MODE_ACCELERATE_FACTOR = 5, /**< Accelerate factor tween mode value */ + EDJE_TWEEN_MODE_DECELERATE_FACTOR = 6, /**< Decelerate factor tween mode value */ + EDJE_TWEEN_MODE_SINUSOIDAL_FACTOR = 7, /**< Sinusoidal factgor tween mode value */ + EDJE_TWEEN_MODE_DIVISOR_INTERP = 8, /**< Divisor iterp tween mode value */ + EDJE_TWEEN_MODE_BOUNCE = 9, /**< Bounce tween mode value */ + EDJE_TWEEN_MODE_SPRING = 10, /**< Spring tween mode value */ + EDJE_TWEEN_MODE_CUBIC_BEZIER = 11, /**< Cubic Bezier tween mode value */ + EDJE_TWEEN_MODE_LAST = 12, /**< Last tween mode value */ + EDJE_TWEEN_MODE_MASK = 0xff, /**< Mask tween mode value */ + EDJE_TWEEN_MODE_OPT_FROM_CURRENT = (1 << 31) /**< Options from current tween mode value */ } Edje_Tween_Mode; +/** + * @typedef Edje_Action_Type + * + * All actions available in Edje programs. + * + */ typedef enum _Edje_Action_Type { - EDJE_ACTION_TYPE_NONE = 0, - EDJE_ACTION_TYPE_STATE_SET = 1, - EDJE_ACTION_TYPE_ACTION_STOP = 2, - EDJE_ACTION_TYPE_SIGNAL_EMIT = 3, - EDJE_ACTION_TYPE_DRAG_VAL_SET = 4, - EDJE_ACTION_TYPE_DRAG_VAL_STEP = 5, - EDJE_ACTION_TYPE_DRAG_VAL_PAGE = 6, - EDJE_ACTION_TYPE_SCRIPT = 7, - EDJE_ACTION_TYPE_FOCUS_SET = 8, - EDJE_ACTION_TYPE_RESERVED00 = 9, - EDJE_ACTION_TYPE_FOCUS_OBJECT = 10, - EDJE_ACTION_TYPE_PARAM_COPY = 11, - EDJE_ACTION_TYPE_PARAM_SET = 12, - EDJE_ACTION_TYPE_SOUND_SAMPLE = 13, /**< @since 1.1 */ - EDJE_ACTION_TYPE_SOUND_TONE = 14, /**< @since 1.1 */ - EDJE_ACTION_TYPE_PHYSICS_IMPULSE = 15, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_TORQUE_IMPULSE = 16, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_FORCE = 17, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_TORQUE = 18, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_FORCES_CLEAR = 19, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_VEL_SET = 20, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_ANG_VEL_SET = 21, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_STOP = 22, /**< @since 1.8 */ - EDJE_ACTION_TYPE_PHYSICS_ROT_SET = 23, /**< @since 1.8 */ - EDJE_ACTION_TYPE_VIBRATION_SAMPLE = 24, /**< @since 1.10 */ - EDJE_ACTION_TYPE_LAST = 25 + EDJE_ACTION_TYPE_NONE = 0, /**< None action value */ + EDJE_ACTION_TYPE_STATE_SET = 1, /**< State set action value */ + EDJE_ACTION_TYPE_ACTION_STOP = 2, /**< Action stop action value */ + EDJE_ACTION_TYPE_SIGNAL_EMIT = 3, /**< Signal emit action value */ + EDJE_ACTION_TYPE_DRAG_VAL_SET = 4, /**< Drag val set action value */ + EDJE_ACTION_TYPE_DRAG_VAL_STEP = 5, /**< Drag val step action value */ + EDJE_ACTION_TYPE_DRAG_VAL_PAGE = 6, /**< Drag val page action value */ + EDJE_ACTION_TYPE_SCRIPT = 7, /**< Script action value */ + EDJE_ACTION_TYPE_FOCUS_SET = 8, /**< Forcus set action value */ + EDJE_ACTION_TYPE_RESERVED00 = 9, /**< Reversed do action value */ + EDJE_ACTION_TYPE_FOCUS_OBJECT = 10, /**< Forcus object action value */ + EDJE_ACTION_TYPE_PARAM_COPY = 11, /**< Param copy action value */ + EDJE_ACTION_TYPE_PARAM_SET = 12, /**< Param set action value */ + EDJE_ACTION_TYPE_SOUND_SAMPLE = 13, /**< @since 1.1 @brief Sound sample action value */ + EDJE_ACTION_TYPE_SOUND_TONE = 14, /**< @since 1.1 @brief Sound tone action value */ + EDJE_ACTION_TYPE_PHYSICS_IMPULSE = 15, /**< @since 1.8 @brief Physics impulse action value */ + EDJE_ACTION_TYPE_PHYSICS_TORQUE_IMPULSE = 16, /**< @since 1.8 @brief Physics torque impulse action value */ + EDJE_ACTION_TYPE_PHYSICS_FORCE = 17, /**< @since 1.8 @brief Physics force action value */ + EDJE_ACTION_TYPE_PHYSICS_TORQUE = 18, /**< @since 1.8 @brief Physics torque action value */ + EDJE_ACTION_TYPE_PHYSICS_FORCES_CLEAR = 19, /**< @since 1.8 @brief Physics forces clear action value */ + EDJE_ACTION_TYPE_PHYSICS_VEL_SET = 20, /**< @since 1.8 @brief Physics velocity set action value */ + EDJE_ACTION_TYPE_PHYSICS_ANG_VEL_SET = 21, /**< @since 1.8 @brief Physics angle velocity set action value */ + EDJE_ACTION_TYPE_PHYSICS_STOP = 22, /**< @since 1.8 @brief Physics stop action value */ + EDJE_ACTION_TYPE_PHYSICS_ROT_SET = 23, /**< @since 1.8 @brief Physics rotation set action value */ + EDJE_ACTION_TYPE_VIBRATION_SAMPLE = 24, /**< @since 1.10 @brief vibration sample action value */ + EDJE_ACTION_TYPE_LAST = 25 /**< Last action value */ } Edje_Action_Type; /** From 11d62ac4f3c2606f6b784f542fb5a6791bab65dd Mon Sep 17 00:00:00 2001 From: Philippe Caseiro Date: Fri, 17 Oct 2014 16:32:17 +0200 Subject: [PATCH 32/55] edje_convert: updating function documentation. --- src/lib/edje/edje_convert.h | 46 ++++++++++++++++++++++++++++++++++--- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/src/lib/edje/edje_convert.h b/src/lib/edje/edje_convert.h index fcc2781f49..4d0248a510 100644 --- a/src/lib/edje/edje_convert.h +++ b/src/lib/edje/edje_convert.h @@ -131,13 +131,53 @@ struct _Old_Edje_Part_Description Eina_List *external_params; /* parameters for external objects */ }; +/** + * Convert old edje files into new edje files + * + * @param file an Eet_File to write the new edje file + * @param oedf the old edje file + * + * @return An Edje_File pointer to the converted file + */ Edje_File *_edje_file_convert(Eet_File *file, Old_Edje_File *oedf); + +/** + * Convert old edje part collection into the new edje file + * + * @param file an Eet_File to write the new edje file + * @param oedc The old edje part collection + * + * @return a new edje parte collection + */ Edje_Part_Collection *_edje_collection_convert(Edje_File *file, - Old_Edje_Part_Collection *oedc); + Old_Edje_Part_Collection *oedc); + +/** + * Convert old edje part descripton into new format + * + * @param type The edje par description common type + * @param ce an edje collection directory entry + * @param the old edje part descripton + * + * @return a new edje part descripton common + */ Edje_Part_Description_Common *_edje_description_convert(int type, - Edje_Part_Collection_Directory_Entry *ce, - Old_Edje_Part_Description *oed); + Edje_Part_Collection_Directory_Entry *ce, + Old_Edje_Part_Description *oed); + +/** + * Get the current edje file + * + * @return the current edje file + */ const Edje_File *_edje_file_get(void); + +/** + * Set the current edje file + * + * @param edf the edje file to set + * + */ void _edje_file_set(const Edje_File *edf); #endif From d7600d6b559f02d8aff410761487617a59587805 Mon Sep 17 00:00:00 2001 From: Chidambar Zinnoury Date: Fri, 17 Oct 2014 17:08:26 +0200 Subject: [PATCH 33/55] edje: documentation for edje_convert.h. --- src/lib/edje/edje_convert.h | 234 +++++++++++++++++++++--------------- 1 file changed, 136 insertions(+), 98 deletions(-) diff --git a/src/lib/edje/edje_convert.h b/src/lib/edje/edje_convert.h index 4d0248a510..c37afd7bb8 100644 --- a/src/lib/edje/edje_convert.h +++ b/src/lib/edje/edje_convert.h @@ -1,72 +1,98 @@ #ifndef EDJE_CONVERT_H__ # define EDJE_CONVERT_H__ -typedef struct _Old_Edje_Image_Directory Old_Edje_Image_Directory; -typedef struct _Old_Edje_Font_Directory Old_Edje_Font_Directory; -typedef struct _Old_Edje_External_Directory Old_Edje_External_Directory; -typedef struct _Old_Edje_Part Old_Edje_Part; -typedef struct _Old_Edje_Part_Collection Old_Edje_Part_Collection; -typedef struct _Old_Edje_Part_Description Old_Edje_Part_Description; -typedef struct _Old_Edje_Part_Description_Spec_Image Old_Edje_Part_Description_Spec_Image; -typedef struct _Edje_Data Edje_Data; +typedef struct _Old_Edje_Image_Directory Old_Edje_Image_Directory; /**< An old Edje image directory */ +typedef struct _Old_Edje_Font_Directory Old_Edje_Font_Directory; /**< An old Edje font directory */ +typedef struct _Old_Edje_External_Directory Old_Edje_External_Directory; /**< An old Edje external directory */ +typedef struct _Old_Edje_Part Old_Edje_Part; /**< An old Edje part */ +typedef struct _Old_Edje_Part_Collection Old_Edje_Part_Collection; /**< An old Edje part collection */ +typedef struct _Old_Edje_Part_Description Old_Edje_Part_Description; /**< An old Edje part description */ +typedef struct _Old_Edje_Part_Description_Spec_Image Old_Edje_Part_Description_Spec_Image; /**< An old Edje part description image */ +typedef struct _Edje_Data Edje_Data; /**< A key/value tuple */ + +/** + * @struct _Edje_Data + * @brief A structure that stores a key/value tuple. + */ struct _Edje_Data { - const char *key; - char *value; + const char *key; /**< key name */ + char *value; /**< contents value */ }; /*----------*/ +/** + * @struct _Old_Edje_Font_Directory + * @brief A structure that stores old font directory entries. + */ struct _Old_Edje_Font_Directory { - Eina_List *entries; /* a list of Edje_Font_Directory_Entry */ + Eina_List *entries; /**< a list of Edje_Font_Directory_Entry */ }; +/** + * @struct _Old_Edje_Image_Directory + * @brief A structure that stores old image directory entries. + */ struct _Old_Edje_Image_Directory { - Eina_List *entries; /* a list of Edje_Image_Directory_Entry */ - Eina_List *sets; /* a list of Edje_Image_Directory_Set */ + Eina_List *entries; /**< a list of Edje_Image_Directory_Entry */ + Eina_List *sets; /**< a list of Edje_Image_Directory_Set */ }; +/** + * @struct _Old_Edje_External_Directory + * @brief A structure that stores old external directory entries. + */ struct _Old_Edje_External_Directory { - Eina_List *entries; /* a list of Edje_External_Directory_Entry */ + Eina_List *entries; /**< a list of Edje_External_Directory_Entry */ }; +/** + * @struct _Old_Edje_File + * @brief A structure that stores old Edje files information. + */ struct _Old_Edje_File { - const char *path; - time_t mtime; + const char *path; /**< path */ + time_t mtime; /**< modification time */ - Old_Edje_External_Directory *external_dir; - Old_Edje_Font_Directory *font_dir; - Old_Edje_Image_Directory *image_dir; - Edje_Part_Collection_Directory *collection_dir; - Eina_List *data; - Eina_List *styles; - Eina_List *color_classes; + Old_Edje_External_Directory *external_dir; /**< external directory */ + Old_Edje_Font_Directory *font_dir; /**< fonts directory */ + Old_Edje_Image_Directory *image_dir; /**< images directory */ + Edje_Part_Collection_Directory *collection_dir; /**< collection directory */ + Eina_List *data; /**< list of Edje_Data */ + Eina_List *styles; /**< list of Edje_Style */ + Eina_List *color_classes; /**< list of Edje_Color_Class */ - const char *compiler; - int version; - int feature_ver; + const char *compiler; /**< compiler name */ + int version; /**< Edje version */ + int feature_ver; /**< features version */ }; +/** + * @struct _Old_Edje_Part_Collection + * @brief A structure that stores old Edje part collection information. + */ struct _Old_Edje_Part_Collection { - Eina_List *programs; /* a list of Edje_Program */ - Eina_List *parts; /* a list of Edje_Part */ - Eina_List *data; + Eina_List *programs; /**< a list of Edje_Program */ + Eina_List *parts; /**< a list of Edje_Part */ + Eina_List *data; /**< a list of Edje_Data */ - int id; /* the collection id */ + int id; /**< the collection id */ - Eina_Hash *alias; /* aliasing part*/ + Eina_Hash *alias; /**< aliasing part*/ struct { - Edje_Size min, max; + Edje_Size min; /**< minimum size */ + Edje_Size max; /**< maximum size */ } prop; - int references; + int references; /**< references count */ #ifdef EDJE_PROGRAM_CACHE struct { Eina_Hash *no_matches; @@ -74,86 +100,98 @@ struct _Old_Edje_Part_Collection } prog_cache; #endif - Embryo_Program *script; /* all the embryo script code for this group */ - const char *part; + Embryo_Program *script; /**< all the embryo script code for this group */ + const char *part; /**< part name */ - unsigned char script_only; + unsigned char script_only; /**< script only */ - unsigned char lua_script_only; + unsigned char lua_script_only; /** LUA script only */ - unsigned char checked : 1; -}; - -struct _Old_Edje_Part -{ - const char *name; /* the name if any of the part */ - Old_Edje_Part_Description *default_desc; /* the part descriptor for default */ - Eina_List *other_desc; /* other possible descriptors */ - const char *source, *source2, *source3, *source4, *source5, *source6; - int id; /* its id number */ - int clip_to_id; /* the part id to clip this one to */ - Edje_Part_Dragable dragable; - Eina_List *items; /* packed items for box and table */ - unsigned char type; /* what type (image, rect, text) */ - unsigned char effect; /* 0 = plain... */ - unsigned char mouse_events; /* it will affect/respond to mouse events */ - unsigned char repeat_events; /* it will repeat events to objects below */ - Evas_Event_Flags ignore_flags; - unsigned char scale; /* should certain properties scale with edje scale factor? */ - unsigned char precise_is_inside; - unsigned char use_alternate_font_metrics; - unsigned char pointer_mode; - unsigned char entry_mode; - unsigned char select_mode; - unsigned char multiline; - Edje_Part_Api api; -}; - -struct _Old_Edje_Part_Description_Spec_Image -{ - Eina_List *tween_list; /* list of Edje_Part_Image_Id */ - int id; /* the image id to use */ - int scale_hint; /* evas scale hint */ - Eina_Bool set; /* if image condition it's content */ - - Edje_Part_Description_Spec_Border border; - Edje_Part_Description_Spec_Fill fill; -}; - -struct _Old_Edje_Part_Description -{ - Edje_Part_Description_Common common; - Old_Edje_Part_Description_Spec_Image image; - Edje_Part_Description_Spec_Text text; - Edje_Part_Description_Spec_Box box; - Edje_Part_Description_Spec_Table table; - - Eina_List *external_params; /* parameters for external objects */ + unsigned char checked : 1; /**< contents checked and registered */ }; /** - * Convert old edje files into new edje files + * @struct _Old_Edje_Part + * @brief A structure that stores old Edje part information. + */ +struct _Old_Edje_Part +{ + const char *name; /**< the name if any of the part */ + Old_Edje_Part_Description *default_desc; /**< the part descriptor for default */ + Eina_List *other_desc; /**< other possible descriptors */ + const char *source, *source2, *source3, *source4, *source5, *source6; + int id; /**< its id number */ + int clip_to_id; /**< the part id to clip this one to */ + Edje_Part_Dragable dragable; /**< dragable part */ + Eina_List *items; /**< packed items for box and table */ + unsigned char type; /**< what type (image, rect, text) */ + unsigned char effect; /**< 0 = plain... */ + unsigned char mouse_events; /**< it will affect/respond to mouse events */ + unsigned char repeat_events; /**< it will repeat events to objects below */ + Evas_Event_Flags ignore_flags; /**< ignore flags */ + unsigned char scale; /**< should certain properties scale with edje scale factor? */ + unsigned char precise_is_inside; /**< whether is precisely inside */ + unsigned char use_alternate_font_metrics; /**< use alternate font metrics */ + unsigned char pointer_mode; /**< pointer mode */ + unsigned char entry_mode; /**< entry mode */ + unsigned char select_mode; /**< entry selection mode */ + unsigned char multiline; /**< multiline enabled */ + Edje_Part_Api api; /**< part API */ +}; + +/** + * @struct _Old_Edje_Part_Description_Spec_Image + * @brief A structure that stores old Edje part description image information. + */ +struct _Old_Edje_Part_Description_Spec_Image +{ + Eina_List *tween_list; /**< list of Edje_Part_Image_Id */ + int id; /**< the image id to use */ + int scale_hint; /**< evas scale hint */ + Eina_Bool set; /**< if image condition it's content */ + + Edje_Part_Description_Spec_Border border; /**< border settings */ + Edje_Part_Description_Spec_Fill fill; /**< fill settings */ +}; + +/** + * @struct _Old_Edje_Part_Description + * @brief A structure that stores old Edje part description information. + */ +struct _Old_Edje_Part_Description +{ + Edje_Part_Description_Common common; /**< common part description */ + Old_Edje_Part_Description_Spec_Image image; /**< image part description */ + Edje_Part_Description_Spec_Text text; /**< text part description */ + Edje_Part_Description_Spec_Box box; /**< box part description */ + Edje_Part_Description_Spec_Table table; /**< table part description */ + + Eina_List *external_params; /**< list of Edje_External_Param */ +}; + +/** + * Convert old Edje files into new Edje files. * - * @param file an Eet_File to write the new edje file - * @param oedf the old edje file + * @param file an Eet_File to write the new Edje file to + * @param oedf the old Edje file * - * @return An Edje_File pointer to the converted file + * @return an Edje_File pointer to the converted file */ Edje_File *_edje_file_convert(Eet_File *file, Old_Edje_File *oedf); /** - * Convert old edje part collection into the new edje file + * Convert old edje part collection into the new Edje file. * - * @param file an Eet_File to write the new edje file - * @param oedc The old edje part collection + * @param file an Eet_File to write the new Edje file to + * @param oedc The Old edje part collection * - * @return a new edje parte collection + * @return a new Edje part collection */ Edje_Part_Collection *_edje_collection_convert(Edje_File *file, Old_Edje_Part_Collection *oedc); /** - * Convert old edje part descripton into new format + * Convert old Edje part descripton into new format. * * @param type The edje par description common type * @param ce an edje collection directory entry @@ -166,16 +204,16 @@ Edje_Part_Description_Common *_edje_description_convert(int type, Old_Edje_Part_Description *oed); /** - * Get the current edje file + * Get the current Edje file. * - * @return the current edje file + * @return the current Edje file */ const Edje_File *_edje_file_get(void); /** - * Set the current edje file + * Set the current Edje file. * - * @param edf the edje file to set + * @param edf the Edje file to set * */ void _edje_file_set(const Edje_File *edf); From b5e417edc42a64fb067c3c6159393cba5dd15ac4 Mon Sep 17 00:00:00 2001 From: Chidambar Zinnoury Date: Fri, 17 Oct 2014 17:14:19 +0200 Subject: [PATCH 34/55] =?UTF-8?q?edje:=20document=20part=20of=20edje=5Fcon?= =?UTF-8?q?tainer.h=20done=20before=20seeing=20all=20of=20edje=5Fcontainer?= =?UTF-8?q?.c=20is=20#if=200=E2=80=99d.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/lib/edje/edje_container.h | 78 +++++++++++++++++++++-------------- 1 file changed, 48 insertions(+), 30 deletions(-) diff --git a/src/lib/edje/edje_container.h b/src/lib/edje/edje_container.h index 0fba62c45d..d7f9a1df99 100644 --- a/src/lib/edje/edje_container.h +++ b/src/lib/edje/edje_container.h @@ -32,36 +32,48 @@ typedef struct _Smart_Data_Colinfo Smart_Data_Colinfo; struct _Smart_Data { - Evas_Coord x, y, w, h; - Eina_List *children; - Evas_Object *smart_obj; - int cols, rows; + Evas_Coord x; /**< horizontal coordinate */ + Evas_Coord y; /**< vertical coordinate */ + Evas_Coord w; /**< width */ + Evas_Coord h; /**< height */ + Eina_List *children; /**< list of children */ + Evas_Object *smart_obj; /**< actual smart object */ + int cols; /**< columns count */ + int rows; /**< rows count */ - Evas_Coord contents_w, contents_h; - Evas_Coord min_row_h, max_row_h; - Evas_Coord min_w, max_w, min_h, max_h; + Evas_Coord contents_w; /**< contents width */ + Evas_Coord contents_h; /**< contents height */ + Evas_Coord min_row_h; /**< minimum row height */ + Evas_Coord max_row_h; /**< maximum row height */ + Evas_Coord min_w; /**< minimum width */ + Evas_Coord max_w; /**< maximum width */ + Evas_Coord min_h; /**< minimum height */ + Evas_Coord max_h; /**< maximum height */ Smart_Data_Colinfo *colinfo; int freeze; - double scroll_x, scroll_y; - double align_x, align_y; + double scroll_x; /**< horizontal scroll */ + double scroll_y; /**< vertical scroll */ + double align_x; /**< horizontal alignment */ + double align_y; /**< vertical alignment */ - unsigned char changed : 1; - unsigned char change_child : 1; - unsigned char change_child_list : 1; - unsigned char change_cols : 1; - unsigned char change_scroll : 1; + unsigned char changed : 1; /**< some property changed */ + unsigned char change_child : 1; /**< a child changed */ + unsigned char change_child_list : 1; /**< child list changed */ + unsigned char change_cols : 1; /**< columns changed */ + unsigned char change_scroll : 1; /**< scroll changed */ - unsigned char need_layout : 1; + unsigned char need_layout : 1; /**< layout computation needed */ - unsigned char homogenous : 1; + unsigned char homogenous : 1; /**< homogeneous layout */ }; struct _Smart_Data_Colinfo { - Evas_Coord minw, maxw; + Evas_Coord minw; /**< minimum width */ + Evas_Coord maxw; /**< maximum width */ }; /* All items are virtual constructs that provide Evas_Objects at some point. @@ -90,36 +102,42 @@ struct _Edje_Item_Class /* private */ struct _Edje_Item { - Edje_Item_Class *class; + Edje_Item_Class *class; /**< item class */ void *class_data; - void *sd; + void *sd; /**< smart data */ void *data; - Evas_Object *object; - Evas_Object *overlay_object; + Evas_Object *object; /**< actual object */ + Evas_Object *overlay_object; /**< overlay object */ int freeze; - Evas_Coord y, h; + Evas_Coord y; /**< vertical position */ + Evas_Coord h; /**< height */ - Evas_Coord minh, maxh; + Evas_Coord minh; /**< minimum height */ + Evas_Coord maxh; /**< maximum height */ - int cells_num; + int cells_num; /**< cells count */ Edje_Item_Cell *cells; unsigned char accessible : 1; unsigned char recalc : 1; - unsigned char selected : 1; - unsigned char disabled : 1; - unsigned char focused : 1; + unsigned char selected : 1; /**< selected item */ + unsigned char disabled : 1; /**< disabled item */ + unsigned char focused : 1; /**< focused item */ }; struct _Edje_Item_Cell { - Evas_Object *obj; - Evas_Coord x, w; - Evas_Coord minw, minh, maxw, maxh; + Evas_Object *obj; /**< actual cell object */ + Evas_Coord x; /**< horizontal position */ + Evas_Coord w; /**< width */ + Evas_Coord minw; /**< minimum width */ + Evas_Coord minh; /**< minimum height */ + Evas_Coord maxw; /**< maximum width */ + Evas_Coord maxh; /**< maximum height */ }; /* here is an item for a vertical list - with 1 or more columns. this has 3 */ From b9fcd48986ce3f283504149090696c7d3a21e9a8 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Fri, 17 Oct 2014 15:39:18 +0200 Subject: [PATCH 35/55] evas: documentation on missing apis --- src/lib/evas/Evas_Common.h | 199 ++++++++++++++++++++++--- src/lib/evas/Evas_Legacy.h | 293 +++++++++++++++++++++++++++++++++++-- 2 files changed, 458 insertions(+), 34 deletions(-) diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h index bc9a62eedd..10313fb553 100644 --- a/src/lib/evas/Evas_Common.h +++ b/src/lib/evas/Evas_Common.h @@ -323,7 +323,7 @@ typedef int Evas_Coord;/**< A type for coordinates */; typedef int Evas_Font_Size; /**< A type for font size */ typedef int Evas_Angle; /**< A type for angle */ -struct _Evas_Coord_Rectangle /**< A rectangle in Evas_Coord */ +struct _Evas_Coord_Rectangle /** A rectangle in Evas_Coord */ { Evas_Coord x; /**< top-left x co-ordinate of rectangle */ Evas_Coord y; /**< top-left y co-ordinate of rectangle */ @@ -331,20 +331,20 @@ struct _Evas_Coord_Rectangle /**< A rectangle in Evas_Coord */ Evas_Coord h; /**< height of rectangle */ }; -struct _Evas_Coord_Point +struct _Evas_Coord_Point /** A Point in Evas_Coord */ { Evas_Coord x; /**< x co-ordinate */ Evas_Coord y; /**< y co-ordinate */ }; -struct _Evas_Coord_Size /**< A size in Evas_Coord */ +struct _Evas_Coord_Size /** A size in Evas_Coord */ { Evas_Coord w; /**< width */ Evas_Coord h; /**< height */ }; -struct _Evas_Coord_Precision_Size +struct _Evas_Coord_Precision_Size /** A size in Evas_Coord with subpixel precision*/ { Evas_Coord w; /**< width */ Evas_Coord h; /**< height */ @@ -352,7 +352,7 @@ struct _Evas_Coord_Precision_Size double ysub; /**< subpixel precision for height */ }; -struct _Evas_Coord_Precision_Point +struct _Evas_Coord_Precision_Point /** A point in Evas_Coord with subpixel precision*/ { Evas_Coord x; /**< x co-ordinate */ Evas_Coord y; /**< y co-ordinate */ @@ -360,19 +360,19 @@ struct _Evas_Coord_Precision_Point double ysub; /**< subpixel precision for y */ }; -struct _Evas_Point +struct _Evas_Point /** A point */ { int x; /**< x co-ordinate */ int y; /**< y co-ordinate */ }; -struct _Evas_Position +struct _Evas_Position /** A position */ { Evas_Point output; /**< position on the output */ Evas_Coord_Point canvas; /**< position on the canvas */ }; -struct _Evas_Precision_Position +struct _Evas_Precision_Position /** A position with precision*/ { Evas_Point output; /**< position on the output */ Evas_Coord_Precision_Point canvas; /**< position on the canvas */ @@ -625,12 +625,12 @@ typedef enum _Evas_Device_Subclass EVAS_DEVICE_SUBCLASS_TRACKBALL, /**< A trackball style mouse @since 1.8 */ } Evas_Device_Subclass; /**< A general class of device @since 1.8 */ -struct _Evas_Engine_Info /**< Generic engine information. Generic info is useless */ +struct _Evas_Engine_Info /** Generic engine information. Generic info is useless */ { int magic; /**< Magic number */ }; -struct _Evas_Event_Mouse_Down /**< Mouse button press event */ +struct _Evas_Event_Mouse_Down /** Mouse button press event */ { int button; /**< Mouse button number that went down (1 - 32) */ @@ -648,7 +648,7 @@ struct _Evas_Event_Mouse_Down /**< Mouse button press event */ Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */ }; -struct _Evas_Event_Mouse_Up /**< Mouse button release event */ +struct _Evas_Event_Mouse_Up /** Mouse button release event */ { int button; /**< Mouse button number that was raised (1 - 32) */ @@ -666,7 +666,7 @@ struct _Evas_Event_Mouse_Up /**< Mouse button release event */ Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */ }; -struct _Evas_Event_Mouse_In /**< Mouse enter event */ +struct _Evas_Event_Mouse_In /** Mouse enter event */ { int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */ @@ -682,7 +682,7 @@ struct _Evas_Event_Mouse_In /**< Mouse enter event */ Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */ }; -struct _Evas_Event_Mouse_Out /**< Mouse leave event */ +struct _Evas_Event_Mouse_Out /** Mouse leave event */ { int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */ @@ -698,7 +698,7 @@ struct _Evas_Event_Mouse_Out /**< Mouse leave event */ Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */ }; -struct _Evas_Event_Mouse_Move /**< Mouse move event */ +struct _Evas_Event_Mouse_Move /** Mouse move event */ { int buttons; /**< Button pressed mask, Bits set to 1 are buttons currently pressed (bit 0 = mouse button 1, bit 1 = mouse button 2 etc.) */ @@ -714,7 +714,7 @@ struct _Evas_Event_Mouse_Move /**< Mouse move event */ Evas_Object *event_src; /**< The Evas Object which actually triggered the event, used in cases of proxy event propagation */ }; -struct _Evas_Event_Mouse_Wheel /**< Wheel event */ +struct _Evas_Event_Mouse_Wheel /** Wheel event */ { int direction; /* 0 = default up/down wheel FIXME: more wheel types */ int z; /* ...,-2,-1 = down, 1,2,... = up */ @@ -730,7 +730,7 @@ struct _Evas_Event_Mouse_Wheel /**< Wheel event */ Evas_Device *dev; }; -struct _Evas_Event_Multi_Down /**< Multi button press event */ +struct _Evas_Event_Multi_Down /** Multi button press event */ { int device; /**< Multi device number that went down (1 or more for extra touches) */ double radius, radius_x, radius_y; @@ -749,7 +749,7 @@ struct _Evas_Event_Multi_Down /**< Multi button press event */ Evas_Device *dev; }; -struct _Evas_Event_Multi_Up /**< Multi button release event */ +struct _Evas_Event_Multi_Up /** Multi button release event */ { int device; /**< Multi device number that went up (1 or more for extra touches) */ double radius, radius_x, radius_y; @@ -768,7 +768,7 @@ struct _Evas_Event_Multi_Up /**< Multi button release event */ Evas_Device *dev; }; -struct _Evas_Event_Multi_Move /**< Multi button down event */ +struct _Evas_Event_Multi_Move /** Multi button down event */ { int device; /**< Multi device number that moved (1 or more for extra touches) */ double radius, radius_x, radius_y; @@ -784,7 +784,7 @@ struct _Evas_Event_Multi_Move /**< Multi button down event */ Evas_Device *dev; }; -struct _Evas_Event_Key_Down /**< Key press event */ +struct _Evas_Event_Key_Down /** Key press event */ { char *keyname; /**< the name string of the key pressed */ void *data; @@ -801,7 +801,7 @@ struct _Evas_Event_Key_Down /**< Key press event */ unsigned int keycode; /**< Key scan code numeric value @since 1.10 */ }; -struct _Evas_Event_Key_Up /**< Key release event */ +struct _Evas_Event_Key_Up /** Key release event */ { char *keyname; /**< the name string of the key released */ void *data; @@ -818,12 +818,12 @@ struct _Evas_Event_Key_Up /**< Key release event */ unsigned int keycode; /**< Key scan code numeric value @since 1.10 */ }; -struct _Evas_Event_Render_Post /**< Send when the frame rendering is done @since 1.8 */ +struct _Evas_Event_Render_Post /** Send when the frame rendering is done @since 1.8 */ { Eina_List *updated_area; /**< A list of rectangle that were updated in the canvas */ }; -struct _Evas_Event_Hold /**< Hold change event */ +struct _Evas_Event_Hold /** Hold change event */ { int hold; /**< The hold flag */ void *data; @@ -2559,18 +2559,173 @@ EAPI void evas_map_point_color_get(const Evas_Map *m, int idx, int *r * @{ */ +/** + * Function signature for the resize event of an evas object + * + * @param data is the pointer passed through the callback. + * @param obj the object being shown. + * + * @see evas_object_intercept_show_callback_add() + * @see evas_object_intercept_show_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Show_Cb)(void *data, Evas_Object *obj); + +/** + * Function signature for the hide event of an evas object + * + * @param data is the pointer passed through the callback. + * @param obj the object being hidden. + * + * @see evas_object_intercept_hide_callback_add() + * @see evas_object_intercept_hide_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Hide_Cb)(void *data, Evas_Object *obj); + +/** + * Function signature for the move event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being moved. + * @param x move x position + * @param y move y position + * + * @see evas_object_intercept_move_callback_add() + * @see evas_object_intercept_move_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Move_Cb)(void *data, Evas_Object *obj, Evas_Coord x, Evas_Coord y); + +/** + * Function signature for the resize event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being resized. + * @param width of the object + * @param height of the object + * + * @see evas_object_intercept_resize_callback_add() + * @see evas_object_intercept_resize_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Resize_Cb)(void *data, Evas_Object *obj, Evas_Coord w, Evas_Coord h); + +/** + * Function signature for the raise event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being raised. + * + * @see evas_object_intercept_raise_callback_add() + * @see evas_object_intercept_raise_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Raise_Cb)(void *data, Evas_Object *obj); + +/** + * Function signature for the lower event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being lowered. + * + * @see evas_object_intercept_lower_callback_add() + * @see evas_object_intercept_lower_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Lower_Cb)(void *data, Evas_Object *obj); + +/** + * Function signature for the stack above event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being stacked above. + * @param above the object above which the object is stacked + * + * @see evas_object_intercept_stack_above_callback_add() + * @see evas_object_intercept_stack_above_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Stack_Above_Cb)(void *data, Evas_Object *obj, Evas_Object *above); + +/** + * Function signature for the stack below event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being stacked below. + * @param above the object below which the object is stacked + * + * @see evas_object_intercept_stack_below_callback_add() + * @see evas_object_intercept_stack_below_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Stack_Below_Cb)(void *data, Evas_Object *obj, Evas_Object *above); + +/** + * Function signature for the layer event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being layered + * @param l the layer value + * + * @see evas_object_intercept_layer_callback_add() + * @see evas_object_intercept_layer_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Layer_Set_Cb)(void *data, Evas_Object *obj, int l); + +/** + * Function signature for the focus set event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being focused + * @param focus the focus value, EINA_TRUE if the object is focused, EINA_FALSE otherwise + * + * @see evas_object_intercept_focus_set_callback_add() + * @see evas_object_intercept_focus_set_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Focus_Set_Cb)(void *data, Evas_Object *obj, Eina_Bool focus); + +/** + * Function signature for the color set event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object changing color + * @param r the red component of the color + * @param g the green component of the color + * @param b the blue component of the color + * @param a the alpha component of the color + * + * @see evas_object_intercept_color_set_callback_add() + * @see evas_object_intercept_color_set_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Color_Set_Cb)(void *data, Evas_Object *obj, int r, int g, int b, int a); + +/** + * Function signature for the clip set event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being clipped + * @param clip the evas object on which the object is clipped + * + * @see evas_object_intercept_clip_set_callback_add() + * @see evas_object_intercept_clip_set_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Clip_Set_Cb)(void *data, Evas_Object *obj, Evas_Object *clip); + +/** + * Function signature for the clip unset event of an evas object + * + * @param data the pointer passed through the callback. + * @param obj the object being unclipped + * + * @see evas_object_intercept_clip_unset_callback_add() + * @see evas_object_intercept_clip_unset_callback_del() + * + */ typedef void (*Evas_Object_Intercept_Clip_Unset_Cb)(void *data, Evas_Object *obj); /** diff --git a/src/lib/evas/Evas_Legacy.h b/src/lib/evas/Evas_Legacy.h index 6c270f1aa8..b33b858f96 100644 --- a/src/lib/evas/Evas_Legacy.h +++ b/src/lib/evas/Evas_Legacy.h @@ -986,7 +986,7 @@ EAPI Evas_Object *evas_object_top_at_pointer_get(const Evas *e) EINA_WARN_UNUSED */ /** - * Set the callback function that intercepts a show event of a object. + * Set the callback function that intercepts a show event of an object. * * @param obj The given canvas object pointer. * @param func The given function to be the callback function. @@ -1001,8 +1001,7 @@ EAPI Evas_Object *evas_object_top_at_pointer_get(const Evas *e) EINA_WARN_UNUSED EAPI void evas_object_intercept_show_callback_add(Evas_Object *obj, Evas_Object_Intercept_Show_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); /** - * Unset the callback function that intercepts a show event of a - * object. + * Unset the callback function that intercepts a show event of a object. * * @param obj The given canvas object pointer. * @param func The given callback function. @@ -1031,8 +1030,7 @@ EAPI void *evas_object_intercept_show_callback_del(Evas_Object *obj, Evas_Object EAPI void evas_object_intercept_hide_callback_add(Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); /** - * Unset the callback function that intercepts a hide event of a - * object. + * Unset the callback function that intercepts a hide event of a object. * * @param obj The given canvas object pointer. * @param func The given callback function. @@ -1046,7 +1044,7 @@ EAPI void evas_object_intercept_hide_callback_add(Evas_Object *obj, Evas_Object EAPI void *evas_object_intercept_hide_callback_del(Evas_Object *obj, Evas_Object_Intercept_Hide_Cb func) EINA_ARG_NONNULL(1, 2); /** - * Set the callback function that intercepts a move event of a object. + * Set the callback function that intercepts a move event of an object. * * @param obj The given canvas object pointer. * @param func The given function to be the callback function. @@ -1061,8 +1059,7 @@ EAPI void *evas_object_intercept_hide_callback_del(Evas_Object *obj, Evas_Object EAPI void evas_object_intercept_move_callback_add(Evas_Object *obj, Evas_Object_Intercept_Move_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); /** - * Unset the callback function that intercepts a move event of a - * object. + * Unset the callback function that intercepts a move event of an object. * * @param obj The given canvas object pointer. * @param func The given callback function. @@ -1075,25 +1072,294 @@ EAPI void evas_object_intercept_move_callback_add(Evas_Object *obj, Evas_Object */ EAPI void *evas_object_intercept_move_callback_del(Evas_Object *obj, Evas_Object_Intercept_Move_Cb func) EINA_ARG_NONNULL(1, 2); +/** + * Set the callback function that intercepts a resize event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a resize event + * of a canvas object. + * + * @see evas_object_intercept_resize_callback_del(). + * + */ EAPI void evas_object_intercept_resize_callback_add(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a resize event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a resize event + * of a canvas object. + * + * @see evas_object_intercept_resize_callback_add(). + * + */ EAPI void *evas_object_intercept_resize_callback_del(Evas_Object *obj, Evas_Object_Intercept_Resize_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a raise event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a raise event + * of a canvas object. + * + * @see evas_object_intercept_raise_callback_del(). + * + */ EAPI void evas_object_intercept_raise_callback_add(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a raise event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a raise event + * of a canvas object. + * + * @see evas_object_intercept_raise_callback_add(). + * + */ EAPI void *evas_object_intercept_raise_callback_del(Evas_Object *obj, Evas_Object_Intercept_Raise_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a lower event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a lower event + * of a canvas object. + * + * @see evas_object_intercept_lower_callback_del(). + * + */ EAPI void evas_object_intercept_lower_callback_add(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a lower event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a lower event + * of a canvas object. + * + * @see evas_object_intercept_lower_callback_add(). + * + */ EAPI void *evas_object_intercept_lower_callback_del(Evas_Object *obj, Evas_Object_Intercept_Lower_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a stack above event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a stack above event + * of a canvas object. + * + * @see evas_object_intercept_stack_above_callback_del(). + * + */ EAPI void evas_object_intercept_stack_above_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a stack above event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a stack above event + * of a canvas object. + * + * @see evas_object_intercept_stack_above_callback_add(). + * + */ EAPI void *evas_object_intercept_stack_above_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Above_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a stack below event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a stack below event + * of a canvas object. + * + * @see evas_object_intercept_stack_below_callback_del(). + * + */ EAPI void evas_object_intercept_stack_below_callback_add(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a stack below event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a stack below event + * of a canvas object. + * + * @see evas_object_intercept_stack_below_callback_add(). + * + */ EAPI void *evas_object_intercept_stack_below_callback_del(Evas_Object *obj, Evas_Object_Intercept_Stack_Below_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a layer set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a layer set event + * of a canvas object. + * + * @see evas_object_intercept_layer_set_callback_del(). + * + */ EAPI void evas_object_intercept_layer_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a layer set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a layer set event + * of a canvas object. + * + * @see evas_object_intercept_layer_set_callback_add(). + * + */ EAPI void *evas_object_intercept_layer_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Layer_Set_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a color set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a color set event + * of a canvas object. + * + * @see evas_object_intercept_color_set_callback_del(). + * + */ EAPI void evas_object_intercept_color_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a color set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a color set event + * of a canvas object. + * + * @see evas_object_intercept_color_set_callback_add(). + * + */ EAPI void *evas_object_intercept_color_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Color_Set_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a clip set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a clip set event + * of a canvas object. + * + * @see evas_object_intercept_clip_set_callback_del(). + * + */ EAPI void evas_object_intercept_clip_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a clip set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a clip set event + * of a canvas object. + * + * @see evas_object_intercept_clip_set_callback_add(). + * + */ EAPI void *evas_object_intercept_clip_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Set_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a clip unset event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a clip unset event + * of a canvas object. + * + * @see evas_object_intercept_clip_unset_callback_del(). + * + */ EAPI void evas_object_intercept_clip_unset_callback_add(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a clip unset event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a clip unset event + * of a canvas object. + * + * @see evas_object_intercept_clip_unset_callback_add(). + * + */ EAPI void *evas_object_intercept_clip_unset_callback_del(Evas_Object *obj, Evas_Object_Intercept_Clip_Unset_Cb func) EINA_ARG_NONNULL(1, 2); + +/** + * Set the callback function that intercepts a focus set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given function to be the callback function. + * @param data The data passed to the callback function. + * + * This function sets a callback function to intercepts a focus set event + * of a canvas object. + * + * @see evas_object_intercept_focus_set_callback_del(). + * + */ EAPI void evas_object_intercept_focus_set_callback_add(Evas_Object *obj, Evas_Object_Intercept_Focus_Set_Cb func, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Unset the callback function that intercepts a focus set event of an object. + * + * @param obj The given canvas object pointer. + * @param func The given callback function. + * + * This function sets a callback function to intercepts a focus set event + * of a canvas object. + * + * @see evas_object_intercept_focus_set_callback_add(). + * + */ EAPI void *evas_object_intercept_focus_set_callback_del(Evas_Object *obj, Evas_Object_Intercept_Focus_Set_Cb func) EINA_ARG_NONNULL(1, 2); /** @@ -2218,27 +2484,30 @@ EAPI Evas_Object *evas_object_grid_add(Evas *evas) EINA_WARN_UNUSED_RESULT EIN */ /** - * @since 1.8 * * Adds an output to the canvas - * + * * @parem e The canvas to add the output to * @return The output * * @see evas_out_engine_info_set * @see evas_output_viewport_set * @see evas_output_size_set + * + * @since 1.8 */ EAPI Evas_Out *evas_out_add(Evas *e); /** - * @since 1.8 * * Deletes an output - * + * * @parem evo The output object * * @see evas_out_add + * + * @since 1.8 + * */ EAPI void evas_output_del(Evas_Out *evo); From a10d8585c9842bf450d3c0c9fdb2738ec3917fac Mon Sep 17 00:00:00 2001 From: Philippe Caseiro Date: Mon, 20 Oct 2014 10:32:39 +0200 Subject: [PATCH 36/55] eio: documentation for return values. - eio_file_copy - eio_file_move - eio_dir_copy - eio_dir_move - eio_dir_unlink --- src/lib/eio/Eio.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/lib/eio/Eio.h b/src/lib/eio/Eio.h index 348ed74d46..e120fd69bd 100644 --- a/src/lib/eio/Eio.h +++ b/src/lib/eio/Eio.h @@ -447,6 +447,8 @@ EAPI Eio_File *eio_file_mkdir(const char *path, * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks * + * @return an Eio_File pointer, handler to the move operation, can be used to cancel the operation + * * This function will copy a file 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 identification. @@ -467,6 +469,8 @@ EAPI Eio_File *eio_file_move(const char *source, * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks * + * @return an Eio_File pointer, handler to the copy operation, can be used to cancel the operation + * * This function will copy a file 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 identification. @@ -488,6 +492,8 @@ EAPI Eio_File *eio_file_copy(const char *source, * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks * + * @return an Eio_File pointer, handler to the move operation, can be used to cancel the operation + * * This function will move a directory and all its content from source to dest. * 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. @@ -516,6 +522,8 @@ EAPI Eio_File *eio_dir_move(const char *source, * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks * + * @return an Eio_File pointer, handler to the copy operation, can be used to cancel the operation + * * This function will copy a directory and all its 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. @@ -540,6 +548,8 @@ EAPI Eio_File *eio_dir_copy(const char *source, * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks * + * @return an Eio_File pointer, handler to the unlink operation, can be used to cancel the operation + * * This function will remove a directory and all its 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 From 57f0a18982258368dc61203245f1f87952833326 Mon Sep 17 00:00:00 2001 From: Nicolas Aguirre Date: Mon, 20 Oct 2014 10:40:21 +0200 Subject: [PATCH 37/55] evas: add documentation about EVAS_MAJOR/MINOR_VERSION. --- src/lib/evas/Evas_Common.h | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h index 10313fb553..e3cdc947a9 100644 --- a/src/lib/evas/Evas_Common.h +++ b/src/lib/evas/Evas_Common.h @@ -2,7 +2,16 @@ # error You shall not include this header directly #endif +/** + * @def EVAS_VERSION_MAJOR + * The major number of evas version + */ #define EVAS_VERSION_MAJOR EFL_VERSION_MAJOR + +/** + * @def EVAS_VERSION_MINOR + * The minor number of eet version + */ #define EVAS_VERSION_MINOR EFL_VERSION_MINOR /** From d22917626c29249727844fd5eb98d81d164e450b Mon Sep 17 00:00:00 2001 From: Adrien Nader Date: Mon, 13 Oct 2014 17:24:27 +0200 Subject: [PATCH 38/55] ecore_audio: add @brief doc for struct Ecore_Audio_Vio. It's simply a copy of the one given in the following typedef: typedef struct _Ecore_Audio_Vio Ecore_Audio_Vio; --- src/lib/ecore_audio/Ecore_Audio.h | 1 + 1 file changed, 1 insertion(+) diff --git a/src/lib/ecore_audio/Ecore_Audio.h b/src/lib/ecore_audio/Ecore_Audio.h index e97706032f..dda0c1bec5 100644 --- a/src/lib/ecore_audio/Ecore_Audio.h +++ b/src/lib/ecore_audio/Ecore_Audio.h @@ -82,6 +82,7 @@ typedef struct _Ecore_Audio_Module Ecore_Audio_Module; typedef struct _Ecore_Audio_Object Ecore_Audio_Object; /**< The audio object */ /* + * @brief Structure to hold the callbacks needed to implement virtual file IO * @since 1.8 */ struct _Ecore_Audio_Vio { From 19a35949dab9b3dfd44a1e063e59132b7ab4f424 Mon Sep 17 00:00:00 2001 From: Adrien Nader Date: Fri, 17 Oct 2014 16:53:40 +0200 Subject: [PATCH 39/55] ethumb: document most functions from ethumb. --- src/lib/ethumb/Ethumb.h | 140 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 138 insertions(+), 2 deletions(-) diff --git a/src/lib/ethumb/Ethumb.h b/src/lib/ethumb/Ethumb.h index 6a1bd4087f..46ab759ad6 100644 --- a/src/lib/ethumb/Ethumb.h +++ b/src/lib/ethumb/Ethumb.h @@ -144,10 +144,26 @@ typedef struct _Ethumb Ethumb; */ typedef void (*Ethumb_Generate_Cb)(void *data, Ethumb *e, Eina_Bool success); +/** + * @brief Initialize ethumb. + * @return 1 or greater on success, 0 otherwise. + */ EAPI int ethumb_init(void); +/** + * @brief Shutdown ethumb, unloading all currently-loaded modules. + * @return 0 if ethumb shuts down, an integer greater than 0 otherwise. + */ EAPI int ethumb_shutdown(void); +/** + * @brief Create a new ethumb object. + * return The newly-created ethumb object + */ EAPI Ethumb * ethumb_new(void) EINA_MALLOC EINA_WARN_UNUSED_RESULT; + +/** + * @brief Free an ethumb object. + */ EAPI void ethumb_free(Ethumb *e); /** @@ -212,22 +228,91 @@ typedef enum _Ethumb_Thumb_Orientation EAPI void ethumb_thumb_fdo_set(Ethumb *e, Ethumb_Thumb_FDO_Size s) EINA_ARG_NONNULL(1); +/** + * @brief Set the size of thumbnails. + * + * @param e A pointer to an Ethumb object. + * @param tw Thumbnail width. + * @param th Thumbnail height. + */ EAPI void ethumb_thumb_size_set(Ethumb *e, int tw, int th) EINA_ARG_NONNULL(1); +/** + * @brief Get the size of thumbnails. + * + * @param e A pointer to an Ethumb object. + * @param[out] tw Pointer to an int to store the thumbnail width. + * @param[out] th Pointer to an int to store the thumbnail height. + */ EAPI void ethumb_thumb_size_get(const Ethumb *e, int *tw, int *th) EINA_ARG_NONNULL(1); +/** + * @brief Set the fileformat of the thumbnails + * + * Thumbnails are sent compressed; possible formats are PNG, JPEG and EET. + * + * @param e A pointer to an Ethumb object. + */ EAPI void ethumb_thumb_format_set(Ethumb *e, Ethumb_Thumb_Format f) EINA_ARG_NONNULL(1); +/** + * @brief Get the fileformat of the thumbnails + * + * @param e A pointer to an Ethumb object. + * @return The thumbnail fileformat + * + * @see ethumb_thumb_format_set + */ EAPI Ethumb_Thumb_Format ethumb_thumb_format_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; -EAPI void ethumb_thumb_aspect_set(Ethumb *e, Ethumb_Thumb_Aspect a) EINA_ARG_NONNULL(1); +/** + * @brief Set the aspect ratio policy. + * + * When the source and thumbnail aspect ratios don't match, this policy sets + * how to adapt from the former to the latter: resize keeping source aspect + * ratio, resize ignoring it or crop. + * + * @param e A pointer to an Ethumb object. + * @param aspect The new aspect ratio policy. + */ +EAPI void ethumb_thumb_aspect_set(Ethumb *e, Ethumb_Thumb_Aspect aspect) EINA_ARG_NONNULL(1); +/** + * @brief Get the aspect ratio policy. + * + * @param e A pointer to an Ethumb object. + * @return The aspect ratio policy. + */ EAPI Ethumb_Thumb_Aspect ethumb_thumb_aspect_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; -EAPI void ethumb_thumb_orientation_set(Ethumb *e, Ethumb_Thumb_Orientation o) EINA_ARG_NONNULL(1); +/** + * @brief Set the thumbnail rotation or flip. + * + * @param e A pointer to an Ethumb object. + * @param orientation The new orientation. + */ +EAPI void ethumb_thumb_orientation_set(Ethumb *e, Ethumb_Thumb_Orientation orientation) EINA_ARG_NONNULL(1); +/** + * @brief Get the thumbnail rotation. + * + * @param e A pointer to an Ethumb object. + * @return The current rotation. + */ EAPI Ethumb_Thumb_Orientation ethumb_thumb_orientation_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI void ethumb_thumb_crop_align_set(Ethumb *e, float x, float y) EINA_ARG_NONNULL(1); EAPI void ethumb_thumb_crop_align_get(const Ethumb *e, float *x, float *y) EINA_ARG_NONNULL(1); +/** + * @brief Set the thumbnail compression quality. + * + * @param e A pointer to an Ethumb object. + * @param quality Compression quality (from 0 to 100, 100 being the best; default is 80) + */ EAPI void ethumb_thumb_quality_set(Ethumb *e, int quality) EINA_ARG_NONNULL(1); +/** + * @brief Get the thumbnail compression quality. + * + * @param e A pointer to an Ethumb object. + * @return The current compression quality (from 0 to 100, 100 being the best) + */ EAPI int ethumb_thumb_quality_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; EAPI void ethumb_thumb_compress_set(Ethumb *e, int compress) EINA_ARG_NONNULL(1); @@ -239,9 +324,35 @@ EAPI void ethumb_video_time_set(Ethumb *e, float time) EINA_ARG_NONNULL( EAPI float ethumb_video_time_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI void ethumb_video_interval_set(Ethumb *e, float interval) EINA_ARG_NONNULL(1); EAPI float ethumb_video_interval_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * @brief Set the number of times the video loops (if applicable). + * + * @param e A pointer to an Ethumb object. + * @param ntimes The number of times the video loops. + */ EAPI void ethumb_video_ntimes_set(Ethumb *e, unsigned int ntimes) EINA_ARG_NONNULL(1); +/** + * @brief Get the number of times the video loops (if applicable). + * + * @param e A pointer to an Ethumb object. + * @return The number of times the video loops. + */ EAPI unsigned int ethumb_video_ntimes_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * @brief Set the thumbnail framerate. + * + * @param e A pointer to an Ethumb object. + * @param fps New framerate of the thumbnail (default 10). + */ EAPI void ethumb_video_fps_set(Ethumb *e, unsigned int fps) EINA_ARG_NONNULL(1); +/** + * @brief Get the thumbnail framerate. + * + * @param e A pointer to an Ethumb object. + * @return Current framerate of the thumbnail. + */ EAPI unsigned int ethumb_video_fps_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; @@ -255,8 +366,33 @@ EAPI unsigned int ethumb_document_page_get(const Ethumb *e) EINA_WARN_UNUSED_RES * @addtogroup Ethumb_Basics Ethumb Basics * @{ */ + +/** + * @brief Set the file for which to generate thumbnails. + * + * @param e A pointer to an Ethumb object. + * @param path The file to use. + * @param key If @a path allows storing multiple resources in a single file + * (EET or Edje for instance), @a key is the key used to locate the + * right resource inside the file. NULL if not applicable. + */ EAPI Eina_Bool ethumb_file_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1, 2); +/** + * @brief Get the file for which to generate thumbnails. + * + * @param e A pointer to an Ethumb object. + * @param[out] path The file being used. + * @param[out] key The key used to locate the right resource in case the file + * can store several of them. NULL if not applicable. + * @see ethumb_file_set + */ EAPI void ethumb_file_get(const Ethumb *e, const char **path, const char **key) EINA_ARG_NONNULL(1); + +/** + * @brief Reset the source file information. + * + * @param e A pointer to an Ethumb object. + */ EAPI void ethumb_file_free(Ethumb *e) EINA_ARG_NONNULL(1); EAPI Eina_Bool ethumb_generate(Ethumb *e, Ethumb_Generate_Cb finished_cb, const void *data, Eina_Free_Cb free_data) EINA_ARG_NONNULL(1, 2); From 73d58b94465dab056ca727941ecb0eebd822d550 Mon Sep 17 00:00:00 2001 From: Adrien Nader Date: Mon, 13 Oct 2014 17:10:05 +0200 Subject: [PATCH 40/55] eio: add doc for returns of eio_file_{mkdir,move,copy}, eio_dir_{move,copy}. --- src/lib/eio/Eio.h | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/lib/eio/Eio.h b/src/lib/eio/Eio.h index e120fd69bd..0eb38c88b0 100644 --- a/src/lib/eio/Eio.h +++ b/src/lib/eio/Eio.h @@ -446,6 +446,7 @@ EAPI Eio_File *eio_file_mkdir(const char *path, * @param done_cb Callback called when the move is done. * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks + * @return A reference to the I/O operation. * * @return an Eio_File pointer, handler to the move operation, can be used to cancel the operation * @@ -491,6 +492,7 @@ EAPI Eio_File *eio_file_copy(const char *source, * @param done_cb Callback called when the copy is done. * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks + * @return A reference to the I/O operation. * * @return an Eio_File pointer, handler to the move operation, can be used to cancel the operation * @@ -521,6 +523,7 @@ EAPI Eio_File *eio_dir_move(const char *source, * @param done_cb Callback called when the copy is done. * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks + * @return A reference to the I/O operation. * * @return an Eio_File pointer, handler to the copy operation, can be used to cancel the operation * @@ -547,6 +550,7 @@ EAPI Eio_File *eio_dir_copy(const char *source, * @param done_cb Callback called when the copy is done. * @param error_cb Callback called when something goes wrong. * @param data Unmodified user data passed to callbacks + * @return A reference to the I/O operation. * * @return an Eio_File pointer, handler to the unlink operation, can be used to cancel the operation * From 513d9efc78cb47f9fe564602c446c53787f95950 Mon Sep 17 00:00:00 2001 From: Philippe Caseiro Date: Mon, 20 Oct 2014 11:41:25 +0200 Subject: [PATCH 41/55] ethumb: update API documentation. - ethumb_frame_set - ethumb_frame_get - ethumb_thumb_dir_path_set - ethumb_thumb_dir_path_get - ethumb_thumb_category_set - ethumb_thumb_category_get --- src/lib/ethumb/Ethumb.h | 51 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/src/lib/ethumb/Ethumb.h b/src/lib/ethumb/Ethumb.h index 46ab759ad6..eaf1bc3dcd 100644 --- a/src/lib/ethumb/Ethumb.h +++ b/src/lib/ethumb/Ethumb.h @@ -179,13 +179,64 @@ EAPI void ethumb_free(Ethumb *e); * @{ */ +/** + * + * @brief Set the Ethumb Frame + * + * This can be used to simulate wood frames in the Thumbnails + * + * @param e handle of the current thumbnailer. + * @param theme_file the edje theme file + * @param group the edje group in theme + * @param swallow the edje swallow in theme + * + * @return EINA_TRUE on success and EINA_FALSE on failure + */ EAPI Eina_Bool ethumb_frame_set(Ethumb *e, const char *theme_file, const char *group, const char *swallow) EINA_ARG_NONNULL(1); + +/** + * @brief Retreives the current ethumb frame of and Ethumb instance. + * + * @param e handle of the current thumbnailer. + * @param theme_file will be setted with the edje theme + * @param group will be setted with the edje group + * @param swallow will be setted with the edje swallow + */ EAPI void ethumb_frame_get(const Ethumb *e, const char **theme_file, const char **group, const char **swallow) EINA_ARG_NONNULL(1); +/** + * @brief Set the ethumb thumbnails path + * + * @param e handle of the current thumbnailer. + * @param path The thumbnails path + * + */ EAPI void ethumb_thumb_dir_path_set(Ethumb *e, const char *path) EINA_ARG_NONNULL(1); + +/** + * @brief Get the ethumb thumbnails path + * + * @param e handle of the current thumbnailer. + * + * @return The thumbnails path for the current thumbnailer + */ EAPI const char *ethumb_thumb_dir_path_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; +/** + * @brief Set the thumbnails category + * + * @param e handle of the current thumbnailer. + * @param category the category to set + */ EAPI void ethumb_thumb_category_set(Ethumb *e, const char *category) EINA_ARG_NONNULL(1); + +/** + * @brief Get the thumbnails category + * + * @param e handle of the current thumbnailer + * + * @return the current thumbnailer thumbnails category + */ EAPI const char *ethumb_thumb_category_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; EAPI void ethumb_thumb_path_set(Ethumb *e, const char *path, const char *key) EINA_ARG_NONNULL(1); From cf1db89a62b3e814e379187e2d8b4fd453efdf3d Mon Sep 17 00:00:00 2001 From: Philippe Caseiro Date: Mon, 20 Oct 2014 12:05:29 +0200 Subject: [PATCH 42/55] etumb: updating API documentation. - ethumb_thumb_compress_set - ethumb_thumb_compress_get - ethumb_video_start_set - ethumb_video_start_get - ethumb_video_time_set - ethumb_video_time_get - ethumb_video_interval_set - ethumb_video_interval_get - ethumb_document_page_set - ethumb_document_page_get --- src/lib/ethumb/Ethumb.h | 80 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 79 insertions(+), 1 deletion(-) diff --git a/src/lib/ethumb/Ethumb.h b/src/lib/ethumb/Ethumb.h index eaf1bc3dcd..65e2a66ce5 100644 --- a/src/lib/ethumb/Ethumb.h +++ b/src/lib/ethumb/Ethumb.h @@ -366,14 +366,80 @@ EAPI void ethumb_thumb_quality_set(Ethumb *e, int quality) EINA_ARG_NONN */ EAPI int ethumb_thumb_quality_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; +/** + * @brief Set the compression rate + * + * @param e handle of the current thumbnailer. + * @param compress the compression rate (in percentage) + * + */ EAPI void ethumb_thumb_compress_set(Ethumb *e, int compress) EINA_ARG_NONNULL(1); + +/** + * @brief Get the compression rate + * + * @param e handle of the current thumbnailer. + * + * @return the compression rate (in percentage) + */ EAPI int ethumb_thumb_compress_get(const Ethumb *e) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; +/** + * @brief set the video play start point + * + * Set the start point of video thumbnail + * + * @param e handle of the current thumbnailer. + * @param start the start point (float from 0.0 to 1.0) + */ EAPI void ethumb_video_start_set(Ethumb *e, float start) EINA_ARG_NONNULL(1); + +/** + * @brief get the video play start point + * + * Get the start point of video thumbnail + * + * @param e handle of the current thumbnailer. + * + * @return the start point (float from 0.0 to 1.0) + */ EAPI float ethumb_video_start_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * @brief Set the video time (duration) in seconds. + * + * @param e handle of the current thumbnailer. + * @param time the video duration in seconds + */ EAPI void ethumb_video_time_set(Ethumb *e, float time) EINA_ARG_NONNULL(1); + +/** + * @brief Get the video time (duration) in seconds. + * + * @param e handle of the current thumbnailer. + * @return the video duration in seconds + */ EAPI float ethumb_video_time_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; + +/** + * @brief Set the video frame interval, in seconds + * + * This is useful for animated thumbnail and will define skip time + * before going to the next frame. Note that video backends might not + * be able to precisely skip that amount as it will depend on various + * factors, including video encoding. + * + * @param e handle of the current thumbnailer. + * @param interval the frame display interval in seconds + */ EAPI void ethumb_video_interval_set(Ethumb *e, float interval) EINA_ARG_NONNULL(1); + +/** + * @brief Get the video frame interval, in seconds + * + * @param e handle of the current thumbnailer. + * @return the frame display interval in seconds + */ EAPI float ethumb_video_interval_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** @@ -406,8 +472,20 @@ EAPI void ethumb_video_fps_set(Ethumb *e, unsigned int fps) EINA_ARG_NON */ EAPI unsigned int ethumb_video_fps_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; - +/** + * @brief Set the page number to thumbnail in paged documents + * + * @param e handle of the current thumbnailer. + * @param page the page number. + */ EAPI void ethumb_document_page_set(Ethumb *e, unsigned int page) EINA_ARG_NONNULL(1); + +/** + * @brief Get the page number thumbnailed in paged documents + * + * @param e handle of the current thumbnailer. + * @return the page number. + */ EAPI unsigned int ethumb_document_page_get(const Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** * @} From de18cf3b8c93f87c2958bbb860e989dc2f6b2a11 Mon Sep 17 00:00:00 2001 From: Philippe Caseiro Date: Mon, 20 Oct 2014 12:17:09 +0200 Subject: [PATCH 43/55] ethumb: update API documentation. - ethumb_generate - ethumb_exists - ethumb_dup - ethumb_cmp --- src/lib/ethumb/Ethumb.h | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/src/lib/ethumb/Ethumb.h b/src/lib/ethumb/Ethumb.h index 65e2a66ce5..5d1fb0c31c 100644 --- a/src/lib/ethumb/Ethumb.h +++ b/src/lib/ethumb/Ethumb.h @@ -524,11 +524,45 @@ EAPI void ethumb_file_get(const Ethumb *e, const char **path, const char ** */ EAPI void ethumb_file_free(Ethumb *e) EINA_ARG_NONNULL(1); +/** + * @brief Generate the thumbnail. + * + * @param e handle of the current thumbnailer. + * @param finished_cb The callback function to run on opertaion end + * @param free_data The callback function to run on free data. + * + * @return EINA_TRUE on success and EINA_FALSE on failure + */ EAPI Eina_Bool ethumb_generate(Ethumb *e, Ethumb_Generate_Cb finished_cb, const void *data, Eina_Free_Cb free_data) EINA_ARG_NONNULL(1, 2); + +/** + * @brief test if the thumbnailer exists + * + * @param e handle of the thumbnailer to test. + * + * @return EINA_TRUE if thumbnailer exists and EINA_FALSE otherwise. + */ EAPI Eina_Bool ethumb_exists(Ethumb *e) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; +/** + * @brief Duplicate an thumbnailer + * + * @param e Handle of the thumbnailer to duplicate + * + * @return a new allocated copy of the thumbnailer. + */ EAPI Ethumb *ethumb_dup(const Ethumb *e) EINA_ARG_NONNULL(1); + +/** + * @brief Compare two thumbnailers. + * + * @param e1 First handle of thumbnailer to compare + * @param e2 Second handle of thumbnailer to compare + * + * @return EINA_TRUE if the thumbnailers are equal and EINA_FALSE otherwise + */ EAPI Eina_Bool ethumb_cmp(const Ethumb *e1, const Ethumb *e2) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT EINA_PURE; + EAPI int ethumb_hash(const void *key, int key_length) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT EINA_PURE; EAPI int ethumb_key_cmp(const void *key1, int key1_length, const void *key2, int key2_length) EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT EINA_PURE; From acfd5a82567c39baf1ad5afb4add97653c05cb0c Mon Sep 17 00:00:00 2001 From: Philippe Caseiro Date: Mon, 20 Oct 2014 15:27:06 +0200 Subject: [PATCH 44/55] emotion: updating API documentation. --- src/lib/emotion/Emotion.h | 51 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/src/lib/emotion/Emotion.h b/src/lib/emotion/Emotion.h index bb41cbeaf9..a776084d38 100644 --- a/src/lib/emotion/Emotion.h +++ b/src/lib/emotion/Emotion.h @@ -367,7 +367,19 @@ extern "C" { * @defgroup Emotion_Ressource Video ressource management */ +/** + * @brief Initialise Emotion library + * + * Initialise needed libraries like eina ecore eet + * Initialise needed modules like webcam + */ EAPI Eina_Bool emotion_init(void); + +/** + * @brief Shutdown Emotion library + * + * Proper shutdown of all loaded modules and initialised libraries. + */ EAPI Eina_Bool emotion_shutdown(void); /** @@ -854,6 +866,15 @@ EAPI void emotion_object_smooth_scale_set (Evas_Object *obj, Eina_B * @ingroup Emotion_Video */ EAPI Eina_Bool emotion_object_smooth_scale_get (const Evas_Object *obj); + +/** + * @brief Send an Emotion Event to an Evas object + * + * @param obj The object target of the event. + * @param ev The emotion event. + * + * @see Emotion_Event + */ EAPI void emotion_object_event_simple_send (Evas_Object *obj, Emotion_Event ev); /** @@ -1004,8 +1025,38 @@ EAPI const char *emotion_object_video_subtitle_file_get (const Evas_Object *ob * @ingroup Emotion_Video */ EAPI int emotion_object_video_channel_count (const Evas_Object *obj); + +/** + * @brief Get the name of a given video channel + * + * @param obj The object which we are retrieving the channel name from + * @param channel the channel number + * @return the channel name. + * + * @see emotion_object_video_channel_count() + * + * @ingroup Emotion_Video + */ EAPI const char *emotion_object_video_channel_name_get(const Evas_Object *obj, int channel); + +/** + * @brief Set the channel for a given video object + * + * @param obj The target object which we are setting the channel + * @param channel the channel number to be setted. + * + * @ingroup Emotion_Video + */ EAPI void emotion_object_video_channel_set (Evas_Object *obj, int channel); + +/** + * @brief Get the channel for a given video object + * + * @param obj The target object which we are getting the channel + * @return The current channel number. + * + * @ingroup Emotion_Video + */ EAPI int emotion_object_video_channel_get (const Evas_Object *obj); EAPI void emotion_object_spu_mute_set (Evas_Object *obj, Eina_Bool mute); EAPI Eina_Bool emotion_object_spu_mute_get (const Evas_Object *obj); From 1c0390bf0889aab75af1bcff01319e813029ee7b Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Thu, 16 Oct 2014 17:43:21 +0200 Subject: [PATCH 45/55] ecore_ipc: update missing API documentation. --- src/lib/ecore/Ecore.h | 2 +- src/lib/ecore_ipc/Ecore_Ipc.h | 90 +++++++++++++++++++++++++---------- 2 files changed, 67 insertions(+), 25 deletions(-) diff --git a/src/lib/ecore/Ecore.h b/src/lib/ecore/Ecore.h index 46bb9673af..a6ac338cab 100644 --- a/src/lib/ecore/Ecore.h +++ b/src/lib/ecore/Ecore.h @@ -39,7 +39,7 @@ @li @ref Ecore_FB_Group @li @ref Ecore_Input_Group @li @ref Ecore_IMF_Lib_Group - @li @link Ecore_Ipc.h Ecore_IPC - Inter Process Communication functions. @endlink + @li @ref Ecore_IPC_Group @li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink @li @ref Ecore_Win32_Group @li @ref Ecore_Audio_Group diff --git a/src/lib/ecore_ipc/Ecore_Ipc.h b/src/lib/ecore_ipc/Ecore_Ipc.h index 71cfa17ed9..a3e38710b4 100644 --- a/src/lib/ecore_ipc/Ecore_Ipc.h +++ b/src/lib/ecore_ipc/Ecore_Ipc.h @@ -30,8 +30,11 @@ #endif /** - * @file Ecore_Ipc.h - * @brief Ecore inter-process communication functions. + * @defgroup Ecore_IPC_Group Ecore_IPC - Ecore inter-process communication functions. + * @ingroup Ecore + * + * + * @{ */ #ifdef __cplusplus @@ -217,6 +220,11 @@ EAPI unsigned long long _ecore_ipc_swap_64(unsigned long long v) EINA_DEPRECATED } \ return d +/** + * @typedef Ecore_Ipc_Type + * + * Enum containing IPC types. + */ typedef enum _Ecore_Ipc_Type { ECORE_IPC_LOCAL_USER, @@ -233,50 +241,81 @@ typedef struct _Ecore_Ipc_Event_Server_Del Ecore_Ipc_Event_Server_Del; typedef struct _Ecore_Ipc_Event_Client_Data Ecore_Ipc_Event_Client_Data; typedef struct _Ecore_Ipc_Event_Server_Data Ecore_Ipc_Event_Server_Data; +/** + * @struct _Ecore_Ipc_Event_Client_Add + * + * An IPC structure for client_add event. + */ struct _Ecore_Ipc_Event_Client_Add { - Ecore_Ipc_Client *client; + Ecore_Ipc_Client *client; /**< An IPC connection handle */ }; +/** + * @struct _Ecore_Ipc_Event_Client_Del + * + * An IPC structure for client_del event. + */ struct _Ecore_Ipc_Event_Client_Del { - Ecore_Ipc_Client *client; + Ecore_Ipc_Client *client; /**< An IPC connection handle */ }; +/** + * @struct _Ecore_Ipc_Event_Server_Add + * + * An IPC structure for server_add event. + */ struct _Ecore_Ipc_Event_Server_Add { - Ecore_Ipc_Server *server; + Ecore_Ipc_Server *server; /**< An IPC connection handle */ }; +/** + * @struct _Ecore_Ipc_Event_Server_Del + * + * An IPC structure for server_del event. + */ struct _Ecore_Ipc_Event_Server_Del { - Ecore_Ipc_Server *server; + Ecore_Ipc_Server *server; /**< An IPC connection handle */ + }; - + +/** + * @struct _Ecore_Ipc_Event_Client_Data + * + * An IPC structure for client_data event. + */ struct _Ecore_Ipc_Event_Client_Data { - Ecore_Ipc_Client *client; + Ecore_Ipc_Client *client; /**< An IPC connection handle */ /* FIXME: this needs to become an ipc message */ - int major; - int minor; - int ref; - int ref_to; - int response; - void *data; - int size; + int major; /**< The message major opcode number */ + int minor; /**< The message minor opcode number */ + int ref; /**< The message reference number */ + int ref_to; /**< Reference number of the message it refers to */ + int response; /**< Requires response */ + void *data; /**< The message data */ + int size; /**< The data length (in bytes) */ }; - + +/** + * @struct _Ecore_Ipc_Event_Server_Data + * + * An IPC structure for server_data event. + */ struct _Ecore_Ipc_Event_Server_Data { - Ecore_Ipc_Server *server; + Ecore_Ipc_Server *server; /**< An IPC connection handle */ /* FIXME: this needs to become an ipc message */ - int major; - int minor; - int ref; - int ref_to; - int response; - void *data; - int size; + int major; /**< The message major opcode number */ + int minor; /**< The message minor opcode number */ + int ref; /**< The message reference number */ + int ref_to; /**< Reference number of the message it refers to */ + int response; /**< Requires response */ + void *data; /**< The message data */ + int size; /**< The data length (in bytes) */ }; EAPI extern int ECORE_IPC_EVENT_CLIENT_ADD; @@ -325,4 +364,7 @@ EAPI int ecore_ipc_ssl_available_get(void); } #endif +/** + * @} + */ #endif From 65db5e981b8f1b749d883469d617c0e2e8c70b89 Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Fri, 17 Oct 2014 15:32:44 +0200 Subject: [PATCH 46/55] eldbus: add missing API documentation in Eldbus.h. --- src/lib/eldbus/Eldbus.h | 48 +++++++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 16 deletions(-) diff --git a/src/lib/eldbus/Eldbus.h b/src/lib/eldbus/Eldbus.h index 220d4ecbb9..3e51b3d3c5 100644 --- a/src/lib/eldbus/Eldbus.h +++ b/src/lib/eldbus/Eldbus.h @@ -116,18 +116,18 @@ extern "C" { * * @{ */ -#define ELDBUS_VERSION_MAJOR EFL_VERSION_MAJOR -#define ELDBUS_VERSION_MINOR EFL_VERSION_MINOR +#define ELDBUS_VERSION_MAJOR EFL_VERSION_MAJOR /**< Eldbus version major number */ +#define ELDBUS_VERSION_MINOR EFL_VERSION_MINOR /**< Eldbus version minor number */ -#define ELDBUS_FDO_BUS "org.freedesktop.DBus" -#define ELDBUS_FDO_PATH "/org/freedesktop/DBus" -#define ELDBUS_FDO_INTERFACE ELDBUS_FDO_BUS -#define ELDBUS_FDO_INTERFACE_PROPERTIES "org.freedesktop.DBus.Properties" -#define ELDBUS_FDO_INTERFACE_OBJECT_MANAGER "org.freedesktop.DBus.ObjectManager" -#define ELDBUS_FDO_INTERFACE_INTROSPECTABLE "org.freedesktop.DBus.Introspectable" -#define ELDBUS_FDO_INTEFACE_PEER "org.freedesktop.DBus.Peer" -#define ELDBUS_ERROR_PENDING_CANCELED "org.enlightenment.DBus.Canceled" -#define ELDBUS_ERROR_PENDING_TIMEOUT "org.freedesktop.DBus.Error.NoReply" +#define ELDBUS_FDO_BUS "org.freedesktop.DBus" /**< Eldbus bus name */ +#define ELDBUS_FDO_PATH "/org/freedesktop/DBus" /**< Eldbus path name */ +#define ELDBUS_FDO_INTERFACE ELDBUS_FDO_BUS /**< Eldbus interface name */ +#define ELDBUS_FDO_INTERFACE_PROPERTIES "org.freedesktop.DBus.Properties" /**< Eldbus object properties request name */ +#define ELDBUS_FDO_INTERFACE_OBJECT_MANAGER "org.freedesktop.DBus.ObjectManager" /**< Eldbus object manager request name */ +#define ELDBUS_FDO_INTERFACE_INTROSPECTABLE "org.freedesktop.DBus.Introspectable" /**< Eldbus object introspect request name */ +#define ELDBUS_FDO_INTEFACE_PEER "org.freedesktop.DBus.Peer" /**< Eldbus object peer request name */ +#define ELDBUS_ERROR_PENDING_CANCELED "org.enlightenment.DBus.Canceled" /**< Eldbus canceled answer */ +#define ELDBUS_ERROR_PENDING_TIMEOUT "org.freedesktop.DBus.Error.NoReply" /**< Eldbus timeout error answer */ /** * @typedef Eldbus_Version @@ -135,13 +135,13 @@ extern "C" { */ typedef struct _Eldbus_Version { - int major; /** < major (binary or source incompatible changes) */ - int minor; /** < minor (new features, bugfixes, major improvements version) */ - int micro; /** < micro (bugfix, internal improvements, no new features version) */ - int revision; /** < git revision (0 if a proper release or the git revision number Eldbus is built from) */ + int major; /**< major (binary or source incompatible changes) */ + int minor; /**< minor (new features, bugfixes, major improvements version) */ + int micro; /**< micro (bugfix, internal improvements, no new features version) */ + int revision; /**< git revision (0 if a proper release or the git revision number Eldbus is built from) */ } Eldbus_Version; -EAPI extern const Eldbus_Version * eldbus_version; +EAPI extern const Eldbus_Version * eldbus_version; /**< Global Eldbus_Version object */ /** * @brief Initialize eldbus. @@ -156,6 +156,11 @@ EAPI int eldbus_init(void); */ EAPI int eldbus_shutdown(void); +/** + * @typedef Eldbus_Free_Cb + * + * Callback that is called when the connection is freed. + */ typedef void (*Eldbus_Free_Cb)(void *data, const void *deadptr); /** @@ -206,7 +211,18 @@ typedef struct _Eldbus_Pending Eldbus_Pending; */ typedef struct _Eldbus_Signal_Handler Eldbus_Signal_Handler; +/** + * @typedef Eldbus_Message_Cb + * + * Callback that is called when answer of a method call message comes. + */ typedef void (*Eldbus_Message_Cb)(void *data, const Eldbus_Message *msg, Eldbus_Pending *pending); + +/** + * @typedef Eldbus_Signal_Cb + * + * Callback that is called when a signal is received. + */ typedef void (*Eldbus_Signal_Cb)(void *data, const Eldbus_Message *msg); /** * @} From 163773ff9f3af5d57273943a50d19cec9c02ea0e Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Fri, 17 Oct 2014 15:33:21 +0200 Subject: [PATCH 47/55] eldbus: update missing API documentation. --- src/lib/eldbus/eldbus_connection.h | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/src/lib/eldbus/eldbus_connection.h b/src/lib/eldbus/eldbus_connection.h index e8542b47a3..10995a7081 100644 --- a/src/lib/eldbus/eldbus_connection.h +++ b/src/lib/eldbus/eldbus_connection.h @@ -7,6 +7,11 @@ * * @{ */ + +/** + * @typedef Eldbus_Connection_Type + * Enum of several Eldbus connection types. + */ typedef enum { ELDBUS_CONNECTION_TYPE_UNKNOWN = 0, /**< sentinel, not a real type */ @@ -17,7 +22,7 @@ typedef enum ELDBUS_CONNECTION_TYPE_LAST /**< sentinel, not a real type */ } Eldbus_Connection_Type; -#define ELDBUS_TIMEOUT_INFINITE ((int) 0x7fffffff) +#define ELDBUS_TIMEOUT_INFINITE ((int) 0x7fffffff) /**< Infinite timeout definition */ /** * Establish a connection to bus and integrate it with the ecore main @@ -70,7 +75,8 @@ EAPI Eldbus_Connection *eldbus_private_address_connection_get(const char *addres /** * @brief Increment connection reference count. * - * @param conn The given Eldbus_Connection object to reference + * @param conn The given Eldbus_Connection object to reference. + * @return The Eldbus_Connection object given as parameter. */ EAPI Eldbus_Connection *eldbus_connection_ref(Eldbus_Connection *conn) EINA_ARG_NONNULL(1); @@ -79,6 +85,8 @@ EAPI Eldbus_Connection *eldbus_connection_ref(Eldbus_Connection *conn) EINA_ARG_ * * If reference count reaches 0, the connection to bus will be dropped and all * its children will be invalidated. + * + * @param conn The given Eldbus_Connection object to unreference. */ EAPI void eldbus_connection_unref(Eldbus_Connection *conn) EINA_ARG_NONNULL(1); @@ -125,6 +133,10 @@ EAPI void *eldbus_connection_data_get(const Eldbus_Connection *conn, */ EAPI void *eldbus_connection_data_del(Eldbus_Connection *conn, const char *key) EINA_ARG_NONNULL(1, 2); +/** + * @typedef Eldbus_Connection_Event_Type + * Enum of several Eldbus connection events. + */ typedef enum { ELDBUS_CONNECTION_EVENT_DEL, @@ -132,6 +144,11 @@ typedef enum ELDBUS_CONNECTION_EVENT_LAST /**< sentinel, not a real event type */ } Eldbus_Connection_Event_Type; +/** + * @typedef Eldbus_Connection_Event_Cb + * + * Callback called when we receive an event. + */ typedef void (*Eldbus_Connection_Event_Cb)(void *data, Eldbus_Connection *conn, void *event_info); /** @@ -155,6 +172,7 @@ EAPI void eldbus_connection_event_callback_del(Eldbus_Connectio * @param cb_data data passed to callback * @param timeout timeout in milliseconds, -1 to use default internal value or * ELDBUS_TIMEOUT_INFINITE for no timeout + * @return A Eldbus_Pending struct. */ EAPI Eldbus_Pending *eldbus_connection_send(Eldbus_Connection *conn, Eldbus_Message *msg, Eldbus_Message_Cb cb, const void *cb_data, double timeout) EINA_ARG_NONNULL(1, 2); From 11b875b6ce43d8d2f95f040e7abe906f44a63cef Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Mon, 20 Oct 2014 11:13:00 +0200 Subject: [PATCH 48/55] eldbus: update missing eldbus_freedesktop.h API documentation. --- src/lib/eldbus/eldbus_freedesktop.h | 183 +++++++++++++++++++++++++++- 1 file changed, 182 insertions(+), 1 deletion(-) diff --git a/src/lib/eldbus/eldbus_freedesktop.h b/src/lib/eldbus/eldbus_freedesktop.h index 8a66b068eb..1b2901ca4d 100644 --- a/src/lib/eldbus/eldbus_freedesktop.h +++ b/src/lib/eldbus/eldbus_freedesktop.h @@ -17,6 +17,16 @@ #define ELDBUS_NAME_REQUEST_REPLY_EXISTS 3 /**< Service is already in the queue */ #define ELDBUS_NAME_REQUEST_REPLY_ALREADY_OWNER 4 /**< Service is already the primary owner */ +/** + * Send a "RequestName" method call in proxy. + * + * @param conn Connection object. + * @param bus Name of the bus + * @param flags Parameter of the "RequestName" method. + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_name_request(Eldbus_Connection *conn, const char *bus, unsigned int flags, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 2); /* Replies to releasing a name */ @@ -24,19 +34,90 @@ EAPI Eldbus_Pending *eldbus_name_request(Eldbus_Connection *conn, const char *bu #define ELDBUS_NAME_RELEASE_REPLY_NON_EXISTENT 2 /**< The given name does not exist on the bus */ #define ELDBUS_NAME_RELEASE_REPLY_NOT_OWNER 3 /**< Service is not an owner of the given name */ +/** + * Send a "ReleaseName" method call in proxy. + * + * @param conn Connection object. + * @param bus Name of the bus + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_name_release(Eldbus_Connection *conn, const char *bus, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 2); + +/** + * Send a "GetNameOwner" method call in proxy. + * + * @param conn Connection object. + * @param bus Name of the bus + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_name_owner_get(Eldbus_Connection *conn, const char *bus, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 2); + +/** + * Send a "NameHasOwner" method call in proxy. + * + * @param conn Connection object. + * @param bus Name of the bus + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_name_owner_has(Eldbus_Connection *conn, const char *bus, Eldbus_Message_Cb cb, const void *cb_data); + +/** + * Send a "ListNames" method call in proxy. + * + * @param conn Connection object. + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_names_list(Eldbus_Connection *conn, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1); + +/** + * Send a "ListActivatableNames" method call in proxy. + * + * @param conn Connection object. + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_names_activatable_list(Eldbus_Connection *conn, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1); + +/** + * Send a "Hello" method call in proxy. + * + * @param conn Connection object. + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_hello(Eldbus_Connection *conn, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1); /* Replies to service starts */ #define ELDBUS_NAME_START_REPLY_SUCCESS 1 /**< Service was auto started */ #define ELDBUS_NAME_START_REPLY_ALREADY_RUNNING 2 /**< Service was already running */ +/** + * Send a "StartServiceByName" method call in proxy. + * + * @param conn Connection object. + * @param bus Name of the bus. + * @param flags Parameter of the "StartServiceByName" method. + * @param cb Callback to call when receiving answer. + * @param cb_data Data passed to callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_name_start(Eldbus_Connection *conn, const char *bus, unsigned int flags, Eldbus_Message_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 2); +/** + * @typedef Eldbus_Name_Owner_Changed_Cb + * + * Callback called when unique id of a bus name changed. + */ typedef void (*Eldbus_Name_Owner_Changed_Cb)(void *data, const char *bus, const char *old_id, const char *new_id); /** @@ -70,7 +151,25 @@ EAPI void eldbus_name_owner_changed_callback_del(Eldbus_Connect * * @{ */ + +/** + * Call the method "Ping" on the eldbus object. + * + * @param obj Eldbus object. + * @param cb Callback called when receiving an answer. + * @param data Data passed to the callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_object_peer_ping(Eldbus_Object *obj, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Call the method "GetMachineId" on the eldbus object. + * + * @param obj Eldbus object. + * @param cb Callback called when receiving an answer. + * @param data Data passed to the callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_object_peer_machine_id_get(Eldbus_Object *obj, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** @@ -82,6 +181,15 @@ EAPI Eldbus_Pending *eldbus_object_peer_machine_id_get(Eldbus_Object *obj * * @{ */ + +/** + * Call the method "Introspect" on the eldbus object. + * + * @param obj Eldbus object. + * @param cb Callback called when receiving an answer. + * @param data Data passed to the callback. + * @return The Eldbus_Pending corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_object_introspect(Eldbus_Object *obj, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** * @} @@ -107,24 +215,72 @@ EAPI Eldbus_Pending *eldbus_object_introspect(Eldbus_Object *obj, Eldbus_ */ EAPI Eina_Bool eldbus_proxy_properties_monitor(Eldbus_Proxy *proxy, Eina_Bool enable) EINA_ARG_NONNULL(1); +/** + * Get a property. + * + * @param proxy The proxy object on which to do the query. + * @param name The property name to get. + * @param cb The callback to be called when receiving an answer. + * @param data Data to be passed to the callback. + * @return Eldbus_Pending object corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_proxy_property_get(Eldbus_Proxy *proxy, const char *name, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * Set a property. + * + * @param proxy The proxy object on which to do the query. + * @param name The property name to get. + * @param sig + * @param value The value to set. + * @param cb The callback to be called when receiving an answer. + * @param data Data to be passed to the callback. + * @return Eldbus_Pending object corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_proxy_property_set(Eldbus_Proxy *proxy, const char *name, const char *sig, const void *value, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2, 3, 4); + +/** + * Get all properties. + * + * @param proxy The proxy object on which to do the query. + * @param cb The callback to be called when receiving an answer. + * @param data Data to be passed to the callback. + * @return Eldbus_Pending object corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_proxy_property_get_all(Eldbus_Proxy *proxy, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); + +/** + * Register a callback on "PropertiesChanged" signal. + * + * @param proxy The proxy object on which to register the callback. + * @param cb The callback to be called when receiving the signal. + * @param data Data to be passed to the callback. + * @return Eldbus_Signal_Handler object representing a listener for "PropertiesChanged" signal. + */ EAPI Eldbus_Signal_Handler *eldbus_proxy_properties_changed_callback_add(Eldbus_Proxy *proxy, Eldbus_Signal_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** * Return the cached value of property. + * * This only work if you have enable eldbus_proxy_properties_monitor or * if you have call eldbus_proxy_event_callback_add of type * ELDBUS_PROXY_EVENT_PROPERTY_CHANGED and the property you want had changed. + * + * @param proxy The proxy object on which to do the query. + * @param name The property name to get. + * @return Cached value of property. */ EAPI Eina_Value *eldbus_proxy_property_local_get(Eldbus_Proxy *proxy, const char *name) EINA_ARG_NONNULL(1, 2); /** - * Return a Eina_Hash with all cached properties. + * Get all cached properties. + * * This only work if you have enable eldbus_proxy_properties_monitor or * if you have call eldbus_proxy_event_callback_add of type * ELDBUS_PROXY_EVENT_PROPERTY_CHANGED. + * + * @param proxy The proxy object on which to do the query. + * @return A Eina_Hash with all cached properties */ EAPI const Eina_Hash *eldbus_proxy_property_local_get_all(Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1); @@ -137,10 +293,35 @@ EAPI const Eina_Hash *eldbus_proxy_property_local_get_all(Eldbus_Proxy *pro * @{ */ +/** + * Call the method "GetManagedObjects" on the eldbus object. + * + * @param obj A Eldbus object. + * @param cb The callback to call when receiving an answer. + * @param data The data to pass to the callback. + * + * @return A Eldbus_Pending object corresponding to the message sent. + */ EAPI Eldbus_Pending *eldbus_object_managed_objects_get(Eldbus_Object *obj, Eldbus_Message_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); +/** + * Register a callback on "InterfacesAdded" signal. + * + * @param obj The Eldbus object on which to register the callback. + * @param cb The callback to be called when receiving the signal. + * @param cb_data Data to be passed to the callback. + * @return Eldbus_Signal_Handler object representing a listener for "InterfacesAdded" signal. + */ EAPI Eldbus_Signal_Handler *eldbus_object_manager_interfaces_added(Eldbus_Object *obj, Eldbus_Signal_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1); +/** + * Register a callback on "InterfacesRemoved" signal. + * + * @param obj The Eldbus object on which to register the callback. + * @param cb The callback to be called when receiving the signal. + * @param cb_data Data to be passed to the callback. + * @return Eldbus_Signal_Handler object representing a listener for "InterfacesRemoved" signal. + */ EAPI Eldbus_Signal_Handler *eldbus_object_manager_interfaces_removed(Eldbus_Object *obj, Eldbus_Signal_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1); /** From de5e028d7dfa7e4b03d958ed0b6213f316c22107 Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Mon, 20 Oct 2014 14:34:45 +0200 Subject: [PATCH 49/55] eldbus: update missing eldbus_message API documentation. --- src/lib/eldbus/eldbus_message.h | 77 +++++++++++++++++++++++--- src/lib/eldbus/eldbus_message_helper.h | 9 +++ 2 files changed, 77 insertions(+), 9 deletions(-) diff --git a/src/lib/eldbus/eldbus_message.h b/src/lib/eldbus/eldbus_message.h index 39bc41efa0..c3e3b8e5c9 100644 --- a/src/lib/eldbus/eldbus_message.h +++ b/src/lib/eldbus/eldbus_message.h @@ -10,6 +10,9 @@ /** * @brief Increase message reference. + * + * @param msg The Eldbus_Message object. + * @return The previous Eldbus_Message with incremented refcount. */ EAPI Eldbus_Message *eldbus_message_ref(Eldbus_Message *msg) EINA_ARG_NONNULL(1); @@ -18,14 +21,57 @@ EAPI Eldbus_Message *eldbus_message_ref(Eldbus_Message *msg) EINA_ARG_NON * * When refcount reaches zero the message and all its resources will be * freed. + * + * @param msg The Eldbus_Message object. */ EAPI void eldbus_message_unref(Eldbus_Message *msg) EINA_ARG_NONNULL(1); +/** + * Get the Eldbus message path. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message path. + */ EAPI const char *eldbus_message_path_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message interface. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message interface. + */ EAPI const char *eldbus_message_interface_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message member. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message member. + */ EAPI const char *eldbus_message_member_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message destination. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message destination. + */ EAPI const char *eldbus_message_destination_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message sender. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message sender. + */ EAPI const char *eldbus_message_sender_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the Eldbus message signature. + * + * @param msg The Eldbus_Message object. + * @return A string containing the dbus message signature. + */ EAPI const char *eldbus_message_signature_get(const Eldbus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** @@ -72,6 +118,7 @@ EAPI Eldbus_Message *eldbus_message_method_return_new(const Eldbus_Messag * desired. * @param text Variable in which to store the error text or @c NULL if it's not * desired. + * @return EINA_TRUE on success, else EINA_FALSE. */ EAPI Eina_Bool eldbus_message_error_get(const Eldbus_Message *msg, const char **name, const char **text) EINA_ARG_NONNULL(1); @@ -79,9 +126,9 @@ EAPI Eina_Bool eldbus_message_error_get(const Eldbus_Message *msg, c * @brief Get the arguments from an Eldbus_Message * * Get the arguments of an Eldbus_Message storing them in the locations pointed - * to by the pointer arguments that follow @param signature. Each pointer + * to by the pointer arguments that follow param signature. Each pointer * argument must be of a type that is appropriate for the correspondent complete - * type in @param signature. For complex types such as arrays, structs, + * type in param signature. For complex types such as arrays, structs, * dictionaries or variants, a pointer to Eldbus_Message_Iter* must be provided. * * @param msg The message to get the arguments from. @@ -98,7 +145,7 @@ EAPI Eina_Bool eldbus_message_arguments_get(const Eldbus_Message *ms * @brief Get the arguments from an Eldbus_Message using a va_list. * * @param msg The message to get the arguments from. - * @param signature The signature user is expecting to read from @param msg. + * @param signature The signature user is expecting to read from param msg. * @param ap The va_list containing the pointer arguments. * * @see eldbus_message_arguments_get() @@ -111,8 +158,8 @@ EAPI Eina_Bool eldbus_message_arguments_vget(const Eldbus_Message *m /** * @brief Append arguments into an Eldbus_Message * - * Append arguments into an Eldbus_Message according to the @param signature - * provided. For each complete type in @param signature, a value of the + * Append arguments into an Eldbus_Message according to the param signature + * provided. For each complete type in param signature, a value of the * corresponding type must be provided. * * This function supports only basic types. For complex types use @@ -120,7 +167,7 @@ EAPI Eina_Bool eldbus_message_arguments_vget(const Eldbus_Message *m * * @param msg The message in which arguments are being appended. * @param signature Signature of the arguments that are being appended. - * @param ... Values of each argument to append in @param msg. + * @param ... Values of each argument to append in param msg. * * @return EINA_TRUE on success, EINA_FALSE otherwise. */ @@ -183,6 +230,7 @@ EAPI Eina_Bool eldbus_message_iter_basic_append(Eldbus_Message_Ite * @param iter iterator in which data will be appended * @param signature signature of the contained data * @param ... values for each complete type + * @return EINA_TRUE on success, else EINA_FALSE * * @see eldbus_message_iter_container_new() * @see eldbus_message_iter_container_close() @@ -206,6 +254,7 @@ EAPI Eina_Bool eldbus_message_iter_arguments_append(Eldbus_Message * @param iter iterator * @param signature of data * @param ap va_list with the values + * @return EINA_TRUE on success, else EINA_FALSE * * @note This function don't support variant, use instead * eldbus_message_iter_container_new() to create the variant fill @@ -221,6 +270,7 @@ EAPI Eina_Bool eldbus_message_iter_arguments_vappend(Eldbus_Messag * @param type basic type that will be appended * @param array data to append * @param size of array + * @return EINA_TRUE on success, else EINA_FALSE */ EAPI Eina_Bool eldbus_message_iter_fixed_array_append(Eldbus_Message_Iter *iter, int type, const void *array, unsigned int size) EINA_ARG_NONNULL(1, 3); @@ -247,6 +297,9 @@ EAPI void eldbus_message_iter_basic_get(Eldbus_Message_Iter * /** * @brief Returns the current signature of a message iterator. * + * @param iter The iterator on which to query the signature. + * @return A string containing the message iterator signature. + * * @note The returned string must be freed. */ EAPI char *eldbus_message_iter_signature_get(Eldbus_Message_Iter *iter) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; @@ -265,14 +318,14 @@ EAPI Eina_Bool eldbus_message_iter_next(Eldbus_Message_Iter *iter) * Useful to iterate over arrays. * * @param iter iterator - * @param type of the next completed type in Iterator + * @param signature of the next completed type in Iterator * @param ... pointer of where data will be stored * - * @param if iterator was reach to end or if type different of the type that + * @return if iterator was reach to end or if type different of the type that * iterator points return EINA_FALSE * */ -EAPI Eina_Bool eldbus_message_iter_get_and_next(Eldbus_Message_Iter *iter, char type, ...) EINA_ARG_NONNULL(1, 2, 3); +EAPI Eina_Bool eldbus_message_iter_get_and_next(Eldbus_Message_Iter *iter, char signature, ...) EINA_ARG_NONNULL(1, 2, 3); /** * @brief Reads a block of fixed-length values from the message iterator. @@ -290,6 +343,12 @@ EAPI Eina_Bool eldbus_message_iter_get_and_next(Eldbus_Message_Ite * * Because the array is not copied, this function runs in constant time and is * fast; it's much preferred over walking the entire array with an iterator. + * + * @param iter The message iterator + * @param signature + * @param value + * @param n_elements + * @return EINA_TRUE on success, else EINA_FALSE. */ EAPI Eina_Bool eldbus_message_iter_fixed_array_get(Eldbus_Message_Iter *iter, int signature, void *value, int *n_elements) EINA_ARG_NONNULL(1, 3, 4); diff --git a/src/lib/eldbus/eldbus_message_helper.h b/src/lib/eldbus/eldbus_message_helper.h index 3009bc1301..584318267f 100644 --- a/src/lib/eldbus/eldbus_message_helper.h +++ b/src/lib/eldbus/eldbus_message_helper.h @@ -5,6 +5,15 @@ * @{ */ +/** + * @typedef Eldbus_Dict_Cb_Get + * + * Callback used when iterating over a dictionary. It is called at each entry iteration. + * + * @param data Context data passed to the callback. + * @param key Key parameter. + * @param var A message iterator on the current entry. + */ typedef void (*Eldbus_Dict_Cb_Get)(void *data, const void *key, Eldbus_Message_Iter *var); /** From 10c4309fa7f366a3a95688c41e1b4d9778c01939 Mon Sep 17 00:00:00 2001 From: Adrien Nader Date: Mon, 20 Oct 2014 13:40:00 +0200 Subject: [PATCH 50/55] eina: remove @addtogroup in eina_inline_mempool.x: the .h already has it. It looks like doxygen doesn't appreciate having a group inside a group of the same name and simply ignores any documentation coming from the parent one. Since the .x is included from the .h, it is always already inside the group so simply remove the directive from the .x. This fixes the documentation for all the functions which are declared and documented in the .h and implemented in the .x. --- src/lib/eina/eina_inline_mempool.x | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/src/lib/eina/eina_inline_mempool.x b/src/lib/eina/eina_inline_mempool.x index 032ce06d81..c33af06971 100644 --- a/src/lib/eina/eina_inline_mempool.x +++ b/src/lib/eina/eina_inline_mempool.x @@ -21,12 +21,6 @@ #include -/** - * @addtogroup Eina_Memory_Pool_Group Memory Pool - * - * @{ - */ - /* Memory Pool */ typedef struct _Eina_Mempool_Backend_ABI1 Eina_Mempool_Backend_ABI1; typedef struct _Eina_Mempool_Backend_ABI2 Eina_Mempool_Backend_ABI2; @@ -128,8 +122,4 @@ eina_mempool_alignof(unsigned int size) return ((size / align) + (size % align ? 1 : 0)) * align; } -/** - * @} - */ - #endif From 020bd415058497a48fc4afa0ae814f2ebe5fa583 Mon Sep 17 00:00:00 2001 From: Adrien Nader Date: Mon, 20 Oct 2014 14:51:37 +0200 Subject: [PATCH 51/55] eina document eina mempools' API. Except for the weird _Eina_Mempool_Backend_ABI1/ABI2 work-around which is completely internal and probably is of interest to noone (the only person on Earth who will be interested in it in a decade will hate me for skipping it). --- src/lib/eina/eina_inline_mempool.x | 16 ++++++++++ src/lib/eina/eina_mempool.h | 48 +++++++++++++++++------------- 2 files changed, 44 insertions(+), 20 deletions(-) diff --git a/src/lib/eina/eina_inline_mempool.x b/src/lib/eina/eina_inline_mempool.x index c33af06971..59bf523e1e 100644 --- a/src/lib/eina/eina_inline_mempool.x +++ b/src/lib/eina/eina_inline_mempool.x @@ -27,14 +27,30 @@ typedef struct _Eina_Mempool_Backend_ABI2 Eina_Mempool_Backend_ABI2; struct _Eina_Mempool_Backend { + /** Name of the mempool backend */ const char *name; + /** Function to initialize the backend. */ void *(*init)(const char *context, const char *options, va_list args); + /** Function to free memory back to the mempool. */ void (*free)(void *data, void *element); + /** Function to allocate memory from the mempool. */ void *(*alloc)(void *data, unsigned int size); + /** Function to change the size of a block of memory that is currently + * allocated. */ void *(*realloc)(void *data, void *element, unsigned int size); + /** Function to trigger a garbage collection; can be NULL if the feature + * isn't available in the backend. */ void (*garbage_collect)(void *data); + /** Report statistics on the content of the mempool; can be NULL if the + * feature isn't available in the backend. */ void (*statistics)(void *data); + /** Function to destroy the backend, freeing memory back to the operating + * system. */ void (*shutdown)(void *data); + /** Function to optimize the placement of objects in the mempool (it's + * different from garbage_collect); can be NULL if the feature isn't + * available in the backend. + * @see Eina_Mempool_Repack_Cb */ void (*repack)(void *data, Eina_Mempool_Repack_Cb cb, void *cb_data); }; diff --git a/src/lib/eina/eina_mempool.h b/src/lib/eina/eina_mempool.h index 9e1d97fcc1..7aaffc2652 100644 --- a/src/lib/eina/eina_mempool.h +++ b/src/lib/eina/eina_mempool.h @@ -71,8 +71,14 @@ typedef struct _Eina_Mempool_Backend Eina_Mempool_Backend; /** * @typedef Eina_Mempool_Repack_Cb - * Type for a callback who need to unreference an old object from a mempool - * and reference the new one instead. Memcpy is taken care by the mempool. + * + * Type for a callback which is called when the mempool "repacks" its data, + * i.e. moves it around to optimize the way it is stored in memory. This is + * useful to improve data locality and to free internal pools back to the OS. + * + * The callback needs to update users of the data to stop accessing the object + * from the old location and access it using the new location instead. The copy + * of memory is taken care of by the mempool. */ typedef void (*Eina_Mempool_Repack_Cb)(void *dst, void *src, void *data); @@ -80,21 +86,22 @@ EAPI extern Eina_Error EINA_ERROR_NOT_MEMPOOL_MODULE; /** * - * @brief TODO + * @brief Create a new mempool of the given type * - * @param module - * @param context - * @param options + * @param name Name of the mempool kind to use. + * @param context Identifier of the mempool created (for debug purposes). + * @param options Unused. Use the variable arguments list instead to pass options to the mempool. + * @param ... Additional options to pass to the allocator; depends entirely on the type of mempool ("int pool size" for chained and "int item_size" for one_big. * @return Newly allocated mempool instance, NULL otherwise. * */ -EAPI Eina_Mempool *eina_mempool_add(const char *module, const char *context, const char *options, ...) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); +EAPI Eina_Mempool *eina_mempool_add(const char *name, const char *context, const char *options, ...) EINA_MALLOC EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1); /** * - * @brief TODO + * @brief Delete the given mempool. * - * @param mp The mempools + * @param mp The mempool to delete * */ EAPI void eina_mempool_del(Eina_Mempool *mp) EINA_ARG_NONNULL(1); @@ -154,19 +161,21 @@ static inline void *eina_mempool_calloc(Eina_Mempool *mp, unsigned int size) EIN static inline void eina_mempool_free(Eina_Mempool *mp, void *element) EINA_ARG_NONNULL(1); /** - * - * @brief TODO + * @brief Repack the objects in the mempool. * * @param mp The mempool - * @param cb The after repack callback - * @param data The data + * @param cb A callback to update the pointers the objects with their new location. + * @param data Data to pass as third argument to @p cb. + * + * @see Eina_Mempool_Repack_Cb + * @see _Eina_Mempool_Backend * */ EAPI void eina_mempool_repack(Eina_Mempool *mp, Eina_Mempool_Repack_Cb cb, void *data) EINA_ARG_NONNULL(1, 2); /** * - * @brief TODO (garbage collect) + * @brief Run a garbage collection cycle. * * @param mp The mempool * @@ -175,7 +184,7 @@ EAPI void eina_mempool_gc(Eina_Mempool *mp) EINA_ARG_NONNULL(1); /** * - * @brief TODO + * @brief Have the backend update its internal statistics. * * @param mp The mempool * @@ -184,7 +193,7 @@ EAPI void eina_mempool_statistics(Eina_Mempool *mp) EINA_ARG_NONNULL(1 /** * - * @brief TODO + * @brief Register the given memory pool backend. * * @param be The backend * @return #EINA_TRUE if backend has been correctly registered, #EINA_FALSE @@ -195,7 +204,7 @@ EAPI Eina_Bool eina_mempool_register(Eina_Mempool_Backend *be) EINA_ARG_NON /** * - * @brief TODO + * @brief Unregister the given memory pool backend. * * @param be The backend * @@ -204,11 +213,10 @@ EAPI void eina_mempool_unregister(Eina_Mempool_Backend *be) EINA_ARG_N /** * - * @brief TODO + * @brief Computer the alignment that would be used when allocating a object of size @p size. * * @param size - * @return #EINA_TRUE if backend has been correctly registered, #EINA_FALSE - * otherwise. + * @return The alignment for an allocation of size @p size. * */ static inline unsigned int eina_mempool_alignof(unsigned int size); From 321f6482cdb7bb13e4097cafe384b936eb6f4cd4 Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Mon, 20 Oct 2014 15:38:49 +0200 Subject: [PATCH 52/55] eldbus: update missing eldbus_object API documentation. --- src/lib/eldbus/eldbus_object.h | 109 +++++++++++++++++++++++++++++---- 1 file changed, 97 insertions(+), 12 deletions(-) diff --git a/src/lib/eldbus/eldbus_object.h b/src/lib/eldbus/eldbus_object.h index 514b40ec0b..297cb0b0f3 100644 --- a/src/lib/eldbus/eldbus_object.h +++ b/src/lib/eldbus/eldbus_object.h @@ -14,17 +14,23 @@ * @param conn connection where object belongs * @param bus name of bus or unique-id of who listens for calls of this object * @param path object path of this object + * @return The corresponding Eldbus_Object. */ EAPI Eldbus_Object *eldbus_object_get(Eldbus_Connection *conn, const char *bus, const char *path) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT; /** * @brief Increase object reference. + * + * @param obj An Eldbus_Object. + * @return The same Eldbus_Object with an increased refcount. */ EAPI Eldbus_Object *eldbus_object_ref(Eldbus_Object *obj) EINA_ARG_NONNULL(1); /** * @brief Decrease object reference. * If reference == 0 object will be freed and all its children. + * + * @param obj An Eldbus_Object. */ EAPI void eldbus_object_unref(Eldbus_Object *obj) EINA_ARG_NONNULL(1); @@ -39,60 +45,128 @@ EAPI void eldbus_object_free_cb_add(Eldbus_Object *obj, Eldbus_Free_Cb /** * @brief Remove callback registered in eldbus_object_free_cb_add(). + * + * @param obj Object monitored. + * @param cb Callback that was registered. + * @param data Data that was passed to callback. */ EAPI void eldbus_object_free_cb_del(Eldbus_Object *obj, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); +/** + * @typedef Eldbus_Object_Event_Type + * + * An enumeration containing several Eldbus_Object event types. + */ typedef enum { ELDBUS_OBJECT_EVENT_IFACE_ADDED = 0, /**< a parent path must have a ObjectManager interface */ ELDBUS_OBJECT_EVENT_IFACE_REMOVED, /**< a parent path must have a ObjectManager interface */ - ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED, - ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED, + ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED, /**< a property has changes */ + ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED, /**< a property was removed */ ELDBUS_OBJECT_EVENT_DEL, ELDBUS_OBJECT_EVENT_LAST /**< sentinel, not a real event type */ } Eldbus_Object_Event_Type; +/** + * @typedef Eldbus_Object_Event_Interface_Added + * + * Structure used with the ELDBUS_OBJECT_EVENT_IFACE_ADDED event. + */ typedef struct _Eldbus_Object_Event_Interface_Added { - const char *interface; - Eldbus_Proxy *proxy; + const char *interface; /**< The interface name */ + Eldbus_Proxy *proxy; /**< The proxy object */ } Eldbus_Object_Event_Interface_Added; +/** + * @typedef Eldbus_Object_Event_Interface_Removed + * + * Structure used with the ELDBUS_OBJECT_EVENT_IFACE_REMOVED event. + */ typedef struct _Eldbus_Object_Event_Interface_Removed { - const char *interface; + const char *interface; /**< The interface name */ } Eldbus_Object_Event_Interface_Removed; +/** + * @typedef Eldbus_Object_Event_Property_Changed + * + * Structure used with the ELDBUS_OBJECT_EVENT_PROPERTY_CHANGED event. + */ typedef struct _Eldbus_Object_Event_Property_Changed { - const char *interface; - Eldbus_Proxy *proxy; - const char *name; - const Eina_Value *value; + const char *interface; /**< The interface name */ + Eldbus_Proxy *proxy; /**< The proxy object */ + const char *name; /**< The name of the property */ + const Eina_Value *value; /**< The value of the property */ } Eldbus_Object_Event_Property_Changed; +/** + * @typedef Eldbus_Object_Event_Property_Removed + * + * Structure used with the ELDBUS_OBJECT_EVENT_PROPERTY_REMOVED event. + */ typedef struct _Eldbus_Object_Event_Property_Removed { - const char *interface; - Eldbus_Proxy *proxy; - const char *name; + const char *interface; /**< The interface name */ + Eldbus_Proxy *proxy; /**< The proxy object */ + const char *name; /**< The name of the property */ } Eldbus_Object_Event_Property_Removed; +/** + * @typedef Eldbus_Object_Event_Cb + * + * Callback that will be called when an Eldbus_Object event happens. + * + * @param data Context data. + * @param obj The Eldbus_Object. + * @param event_info Information about the event that triggered the callback. + */ typedef void (*Eldbus_Object_Event_Cb)(void *data, Eldbus_Object *obj, void *event_info); /** * @brief Add a callback function to be called when an event of the specified * type occurs. + * + * @param obj The Eldbus_Object on which to register a callback. + * @param type The type of the event. + * @param cb The callback to call. + * @param cb_data The data to pass to the callback. */ EAPI void eldbus_object_event_callback_add(Eldbus_Object *obj, Eldbus_Object_Event_Type type, Eldbus_Object_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); /** * @brief Remove callback registered in eldbus_object_event_callback_add(). + * + * @param obj The Eldbus_Object. + * @param type The type of the event. + * @param cb The callback to call. + * @param cb_data The data to pass to the callback. */ EAPI void eldbus_object_event_callback_del(Eldbus_Object *obj, Eldbus_Object_Event_Type type, Eldbus_Object_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); +/** + * Get the Eldbus_Connection object associated with a Eldbus_Object. + * + * @param obj The Eldbus_Object. + * @return The corresponding Eldbus_Connection object. + */ EAPI Eldbus_Connection *eldbus_object_connection_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the name associated with a Eldbus_Object. + * + * @param obj The Eldbus_Object. + * @return A string corresponding to the Eldbus_Object name. + */ EAPI const char *eldbus_object_bus_name_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * Get the path associated with a Eldbus_Object. + * + * @param obj The Eldbus_Object. + * @return A string corresponding to the Eldbus_Object path. + */ EAPI const char *eldbus_object_path_get(const Eldbus_Object *obj) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** @@ -105,6 +179,7 @@ EAPI const char *eldbus_object_path_get(const Eldbus_Object *obj) EINA * @param cb_data data passed to callback * @param timeout timeout in milliseconds, -1 to default internal value or * ELDBUS_TIMEOUT_INFINITE for no timeout + * @return A Eldbus_Pending object. */ EAPI Eldbus_Pending *eldbus_object_send(Eldbus_Object *obj, Eldbus_Message *msg, Eldbus_Message_Cb cb, const void *cb_data, double timeout) EINA_ARG_NONNULL(1, 2); @@ -116,9 +191,19 @@ EAPI Eldbus_Pending *eldbus_object_send(Eldbus_Object *obj, Eldbus_Messag * @param member name of the signal * @param cb callback that will be called when this signal is received * @param cb_data data that will be passed to callback + * @return A listener to the desired signal. */ EAPI Eldbus_Signal_Handler *eldbus_object_signal_handler_add(Eldbus_Object *obj, const char *interface, const char *member, Eldbus_Signal_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 4); +/** + * @brief Call a dbus method on the Eldbus_Object. + * + * @param obj The Eldbus_Object on which to call the method. + * @param interface Interface name. + * @param member Name of the method to be called. + * + * @return a new Eldbus_Message, free with eldbus_message_unref() + */ EAPI Eldbus_Message *eldbus_object_method_call_new(Eldbus_Object *obj, const char *interface, const char *member) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT; /** From a86a8e1e4a14ce6a36acde8ebb7b825e5372ecc5 Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Mon, 20 Oct 2014 16:03:40 +0200 Subject: [PATCH 53/55] eldbus: update missing eldbus_pending.h API documentation. --- src/lib/eldbus/eldbus_pending.h | 63 +++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/src/lib/eldbus/eldbus_pending.h b/src/lib/eldbus/eldbus_pending.h index 98c0085657..8cb8e969ae 100644 --- a/src/lib/eldbus/eldbus_pending.h +++ b/src/lib/eldbus/eldbus_pending.h @@ -8,23 +8,86 @@ * @{ */ +/** + * @brief Set data to a Eldbus_Pending object. + * + * @param pending The Eldbus_Pending object on which the data is set. + * @param key A string corresponding to the key associated with the data. + * @param data The data to set to the Eldbus_Pending object. + */ EAPI void eldbus_pending_data_set(Eldbus_Pending *pending, const char *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Get the data set to a Eldbus_Pending object. + * + * @param pending The Eldbus_Pending object on which the data is set. + * @param key A string corresponding to the key associated with the data. + * @return The data set to the Eldbus_Pending object. + */ EAPI void *eldbus_pending_data_get(const Eldbus_Pending *pending, const char *key) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Delete the data set to a Eldbus_Pending object. + * + * @param pending The Eldbus_Pending object on which the data is set. + * @param key A string corresponding to the key associated with the data. + */ EAPI void *eldbus_pending_data_del(Eldbus_Pending *pending, const char *key) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Cancel the pending message. + * + * @param pending The Eldbus_Pending object corresponding to the pending message. + */ EAPI void eldbus_pending_cancel(Eldbus_Pending *pending) EINA_ARG_NONNULL(1); +/** + * @brief Get the destination of the pending message. + * + * @param pending The Eldbus_Pending object. + * @return A string corresponding to the destination of the message. + */ EAPI const char *eldbus_pending_destination_get(const Eldbus_Pending *pending) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Get the path of the pending message. + * + * @param pending The Eldbus_Pending object. + * @return A string corresponding to the path of the message. + */ EAPI const char *eldbus_pending_path_get(const Eldbus_Pending *pending) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Get the interface of the pending message. + * + * @param pending The Eldbus_Pending object. + * @return A string corresponding to the interface of the message. + */ EAPI const char *eldbus_pending_interface_get(const Eldbus_Pending *pending) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Get the method of the pending message. + * + * @param pending The Eldbus_Pending object. + * @return A string corresponding to the method of the message. + */ EAPI const char *eldbus_pending_method_get(const Eldbus_Pending *pending) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; /** * @brief Add a callback function to be called when pending will be freed. + * + * @param pending The Eldbus_Pending object on which the callback is registered. + * @param cb The callback to register. + * @param data The data to pass to the callback. */ EAPI void eldbus_pending_free_cb_add(Eldbus_Pending *pending, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** * @brief Remove callback registered in eldbus_pending_free_cb_add(). + * + * @param pending The Eldbus_Pending object on which the callback was registered. + * @param cb The callback that was registered. + * @param data The data passed to the callback. */ EAPI void eldbus_pending_free_cb_del(Eldbus_Pending *pending, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); From f50f321562e74306807fe19b5d4a040b9f27ae8c Mon Sep 17 00:00:00 2001 From: Pierre Le Magourou Date: Mon, 20 Oct 2014 16:46:59 +0200 Subject: [PATCH 54/55] eldbus: update missing eldbus_proxy API documentation. --- src/lib/eldbus/eldbus_proxy.h | 120 ++++++++++++++++++++++++++++++---- 1 file changed, 109 insertions(+), 11 deletions(-) diff --git a/src/lib/eldbus/eldbus_proxy.h b/src/lib/eldbus/eldbus_proxy.h index 5752001bd9..5993967439 100644 --- a/src/lib/eldbus/eldbus_proxy.h +++ b/src/lib/eldbus/eldbus_proxy.h @@ -10,40 +10,96 @@ /** * @brief Get a proxy of the following interface name in a Eldbus_Object. + * + * @param obj The Eldbus_Object on which to do the query. + * @param interface The interface name of the proxy. + * @return The corresponding Eldbus_Proxy object. */ EAPI Eldbus_Proxy *eldbus_proxy_get(Eldbus_Object *obj, const char *interface) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; /** * @brief Increase proxy reference. + * + * @param proxy The Eldbus_Proxy on which to increase the refcount. + * @return The Eldbus_Proxy with an increased refcount. */ EAPI Eldbus_Proxy *eldbus_proxy_ref(Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1); /** * @brief Decrease proxy reference. * If reference == 0 proxy will be freed and all your children. + * + * @param proxy The Eldbus_Proxy on which to decrease the refcount. */ EAPI void eldbus_proxy_unref(Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1); +/** + * @brief Get the Eldbus_Object associated with a proxy object. + * + * @param proxy The Eldbus_Proxy on which to do the query. + * @return The corresponding Eldbus_Object. + */ EAPI Eldbus_Object *eldbus_proxy_object_get(const Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; + +/** + * @brief Get the interface name associated with a proxy object. + * + * @param proxy The Eldbus_Proxy on which to do the query. + * @return The string corresponding to the interface name. + */ EAPI const char *eldbus_proxy_interface_get(const Eldbus_Proxy *proxy) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; +/** + * @brief Set data to an Eldbus_Proxy object. + * + * @param proxy The Eldbus_Proxy on which to set the data. + * @param key A string to which the data will be associated. + * @param data The data to set to the proxy object. + */ EAPI void eldbus_proxy_data_set(Eldbus_Proxy *proxy, const char *key, const void *data) EINA_ARG_NONNULL(1, 2, 3); + +/** + * @brief Get data of an Eldbus_Proxy object. + * + * @param proxy The Eldbus_Proxy on which to get the data. + * @param key The string to which the data is associated. + * @return The data set to the proxy object associated with the provided key. + */ EAPI void *eldbus_proxy_data_get(const Eldbus_Proxy *proxy, const char *key) EINA_ARG_NONNULL(1, 2); + +/** + * @brief Delete data of an Eldbus_Proxy object. + * + * @param proxy The Eldbus_Proxy on which to delete the data. + * @param key The string to which the data is associated. + */ EAPI void *eldbus_proxy_data_del(Eldbus_Proxy *proxy, const char *key) EINA_ARG_NONNULL(1, 2); /** - * @brief Add a callback function to be called when occurs a event of the - * type passed. + * @brief Add a callback function to be called when an event of the + * type passed occurs. + * + * @param proxy The Eldbus_Proxy on which to add the callback. + * @param cb The callback to add. + * @param data The data to pass to the callback. */ EAPI void eldbus_proxy_free_cb_add(Eldbus_Proxy *proxy, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** * @brief Remove callback registered in eldbus_proxy_free_cb_add(). + * + * @param proxy The Eldbus_Proxy on which to delete the callback. + * @param cb The callback to delete. + * @param data The data passed to the callback. */ EAPI void eldbus_proxy_free_cb_del(Eldbus_Proxy *proxy, Eldbus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2); /** * @brief Constructs a new message to invoke a method on a remote interface. + * + * @param proxy The Eldbus_Proxy on which to call the method. + * @param member The name of the method to invoke. + * @return An Eldbus_Message object. */ EAPI Eldbus_Message *eldbus_proxy_method_call_new(Eldbus_Proxy *proxy, const char *member) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; @@ -56,6 +112,7 @@ EAPI Eldbus_Message *eldbus_proxy_method_call_new(Eldbus_Proxy *proxy, co * @param cb_data data passed to callback * @param timeout timeout in milliseconds, -1 to default internal value or * ELDBUS_TIMEOUT_INFINITE for no timeout + * @return A Eldbus_Pending object on the sent message. */ EAPI Eldbus_Pending *eldbus_proxy_send(Eldbus_Proxy *proxy, Eldbus_Message *msg, Eldbus_Message_Cb cb, const void *cb_data, double timeout) EINA_ARG_NONNULL(1, 2); @@ -72,6 +129,7 @@ EAPI Eldbus_Pending *eldbus_proxy_send(Eldbus_Proxy *proxy, Eldbus_Messag * ELDBUS_TIMEOUT_INFINITE for no timeout * @param signature of data that will be send * @param ... data value + * @return A Eldbus_Pending object on the sent message. * * @note This function only support basic type to complex types use * eldbus_message_iter_* functions. @@ -90,6 +148,7 @@ EAPI Eldbus_Pending *eldbus_proxy_call(Eldbus_Proxy *proxy, const char *m * ELDBUS_TIMEOUT_INFINITE for no timeout * @param signature of data that will be send * @param ap va_list of data value + * @return A Eldbus_Pending object on the sent message. * * @note This function only support basic type to complex types use * eldbus_message_iter_* functions. @@ -103,47 +162,86 @@ EAPI Eldbus_Pending *eldbus_proxy_vcall(Eldbus_Proxy *proxy, const char * * @param member name of the signal * @param cb callback that will be called when this signal is received * @param cb_data data that will be passed to callback + * @return A listener to the desired signal. */ EAPI Eldbus_Signal_Handler *eldbus_proxy_signal_handler_add(Eldbus_Proxy *proxy, const char *member, Eldbus_Signal_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); +/** + * @typedef Eldbus_Proxy_Event_Type + * + * An enumeration containing proxy event types. + */ typedef enum { - ELDBUS_PROXY_EVENT_PROPERTY_CHANGED = 0, - ELDBUS_PROXY_EVENT_PROPERTY_REMOVED, + ELDBUS_PROXY_EVENT_PROPERTY_CHANGED = 0, /**< a property has changed */ + ELDBUS_PROXY_EVENT_PROPERTY_REMOVED, /**< a property was removed */ ELDBUS_PROXY_EVENT_DEL, ELDBUS_PROXY_EVENT_PROPERTY_LOADED, ELDBUS_PROXY_EVENT_LAST /**< sentinel, not a real event type */ } Eldbus_Proxy_Event_Type; +/** + * @typedef Eldbus_Proxy_Event_Property_Changed + * + * A structure used when ELDBUS_PROXY_EVENT_PROPERTY_CHANGED event is received. + */ typedef struct _Eldbus_Proxy_Event_Property_Changed { - const char *name; - const Eldbus_Proxy *proxy; - const Eina_Value *value; + const char *name; /**< the name of the property */ + const Eldbus_Proxy *proxy; /**< the proxy object */ + const Eina_Value *value; /**< the value of the property */ } Eldbus_Proxy_Event_Property_Changed; +/** + * @typedef Eldbus_Proxy_Event_Property_Loaded + * + * A structure used when ELDBUS_PROXY_EVENT_PROPERTY_LOADED event is received. + */ typedef struct _Eldbus_Proxy_Event_Property_Loaded { - const Eldbus_Proxy *proxy; + const Eldbus_Proxy *proxy; /**< the proxy object */ } Eldbus_Proxy_Event_Property_Loaded; +/** + * @typedef Eldbus_Proxy_Event_Property_Removed + * + * A structure used when ELDBUS_PROXY_EVENT_PROPERTY_REMOVED event is received. + */ typedef struct _Eldbus_Proxy_Event_Property_Removed { - const char *interface; - const Eldbus_Proxy *proxy; - const char *name; + const char *interface; /**< interface name */ + const Eldbus_Proxy *proxy; /**< the proxy object */ + const char *name; /**< the name of the property */ } Eldbus_Proxy_Event_Property_Removed; +/** + * @typedef Eldbus_Proxy_Event_Cb + * + * A callback called when an event occurs. + * @param data The data passed by the caller. + * @param proxy The Eldbus_Proxy object. + * @param event_info Information on the event that triggered the callback. + */ typedef void (*Eldbus_Proxy_Event_Cb)(void *data, Eldbus_Proxy *proxy, void *event_info); /** * @brief Add a callback function to be called when occurs a event of the * type passed. + * + * @param proxy The Eldbus_Proxy object. + * @param type The type of the event to register an callback on. + * @param cb The callback function to register. + * @param cb_data The data to pass to the callback. */ EAPI void eldbus_proxy_event_callback_add(Eldbus_Proxy *proxy, Eldbus_Proxy_Event_Type type, Eldbus_Proxy_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); /** * @brief Remove callback registered in eldbus_proxy_event_callback_add(). + * + * @param proxy The Eldbus_Proxy object. + * @param type The type of the event the callback was registered on. + * @param cb The callback function to delete. + * @param cb_data The data passed to the callback. */ EAPI void eldbus_proxy_event_callback_del(Eldbus_Proxy *proxy, Eldbus_Proxy_Event_Type type, Eldbus_Proxy_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3); From b473a56733efa890dbd9962306ad597fa08c6614 Mon Sep 17 00:00:00 2001 From: Chidambar Zinnoury Date: Mon, 20 Oct 2014 16:54:56 +0200 Subject: [PATCH 55/55] eet: add some more documentation. --- src/lib/eet/Eet.h | 99 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 82 insertions(+), 17 deletions(-) diff --git a/src/lib/eet/Eet.h b/src/lib/eet/Eet.h index 25029396ba..b3451fa4fa 100644 --- a/src/lib/eet/Eet.h +++ b/src/lib/eet/Eet.h @@ -4241,7 +4241,10 @@ struct _Eet_Node_Data */ /** - * TODO FIX ME + * Create a new character node. + * @param name Name of the node. + * @param c Character value. + * @return A new character node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4249,7 +4252,10 @@ eet_node_char_new(const char *name, char c); /** - * TODO FIX ME + * Create a new short node. + * @param name Name of the node. + * @param s short value. + * @return A new short node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4257,7 +4263,10 @@ eet_node_short_new(const char *name, short s); /** - * TODO FIX ME + * Create a new integer node. + * @param name Name of the node. + * @param i integer value. + * @return A new integer node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4265,7 +4274,10 @@ eet_node_int_new(const char *name, int i); /** - * TODO FIX ME + * Create a new long long integer node. + * @param name Name of the node. + * @param l long long integer value. + * @return A new long long integer node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4273,7 +4285,10 @@ eet_node_long_long_new(const char *name, long long l); /** - * TODO FIX ME + * Create a new float node. + * @param name Name of the node. + * @param f float value. + * @return A new float node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4281,7 +4296,10 @@ eet_node_float_new(const char *name, float f); /** - * TODO FIX ME + * Create a new double node. + * @param name Name of the node. + * @param d double value. + * @return A new double node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4289,7 +4307,10 @@ eet_node_double_new(const char *name, double d); /** - * TODO FIX ME + * Create a new unsigned character node. + * @param name Name of the node. + * @param uc unsigned char value. + * @return A new unsigned char node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4297,7 +4318,10 @@ eet_node_unsigned_char_new(const char *name, unsigned char uc); /** - * TODO FIX ME + * Create a new unsigned short node. + * @param name Name of the node. + * @param us unsigned short value. + * @return A new unsigned short node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4305,7 +4329,10 @@ eet_node_unsigned_short_new(const char *name, unsigned short us); /** - * TODO FIX ME + * Create a new unsigned integer node. + * @param name Name of the node. + * @param ui unsigned integer value. + * @return A new unsigned integer node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4313,7 +4340,10 @@ eet_node_unsigned_int_new(const char *name, unsigned int ui); /** - * TODO FIX ME + * Create a new unsigned long long integer node. + * @param name Name of the node. + * @param l unsigned long long integer value. + * @return A new unsigned long long integer node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4321,7 +4351,10 @@ eet_node_unsigned_long_long_new(const char *name, unsigned long long l); /** - * TODO FIX ME + * Create a new string node. + * @param name Name of the node. + * @param str string value. + * @return A new string node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4329,7 +4362,10 @@ eet_node_string_new(const char *name, const char *str); /** - * TODO FIX ME + * Create a new inlined string node. + * @param name Name of the node. + * @param str string value. + * @return A new inlined string node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4337,14 +4373,19 @@ eet_node_inlined_string_new(const char *name, const char *str); /** - * TODO FIX ME + * Create a new empty node. + * @param name Name of the node. + * @return A new empty node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * eet_node_null_new(const char *name); /** - * TODO FIX ME + * Create a new list node. + * @param name Name of the node. + * @param nodes list of nodes. + * @return A new list node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4352,7 +4393,11 @@ eet_node_list_new(const char *name, Eina_List *nodes); /** - * TODO FIX ME + * Create a new array node. + * @param name Name of the node. + * @param count number of nodes + * @param nodes list of nodes. + * @return A new array node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4361,7 +4406,10 @@ eet_node_array_new(const char *name, Eina_List *nodes); /** - * TODO FIX ME + * Create a new variable array node. + * @param name Name of the node. + * @param nodes list of nodes. + * @return A new variable array node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4372,13 +4420,23 @@ eet_node_var_array_new(const char *name, * TODO FIX ME * @ingroup Eet_Node_Group */ +/** + * Create a new short node. + * @param name Name of the node. + * @param s short value. + * @return A new short node. + * @ingroup Eet_Node_Group + */ EAPI Eet_Node * eet_node_hash_new(const char *name, const char *key, Eet_Node *node); /** - * TODO FIX ME + * Create a new struct node. + * @param name Name of the node. + * @param nodes list of nodes. + * @return A new struct node. * @ingroup Eet_Node_Group */ EAPI Eet_Node * @@ -4389,6 +4447,13 @@ eet_node_struct_new(const char *name, * TODO FIX ME * @ingroup Eet_Node_Group */ +/** + * Create a new short node. + * @param name Name of the node. + * @param s short value. + * @return A new short node. + * @ingroup Eet_Node_Group + */ EAPI Eet_Node * eet_node_struct_child_new(const char *parent, Eet_Node *child);