From: Xavi Artigas Date: Tue, 14 Apr 2020 14:11:04 +0000 (+0200) Subject: doxygen docs: Proper usage of @ingroup and @addtogroup X-Git-Tag: submit/tizen/20200416.001154~10 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=8cbbdf3b4d50ed4be9bf34006264a9c53b1f6297;p=platform%2Fupstream%2Fefl.git doxygen docs: Proper usage of @ingroup and @addtogroup This patch brings in a lot of docs which were missing before. Unfortunately, this brings along their warnings so this ends up adding more warnings than it fixes. Still, a step in the right direction. @ingroup puts the current block into the specified group, but IT DOES NOT allow opening groups with @{. This was used in lots of places, resulting in misplaced or ignored documentation. @ingroup should be used only in individual docs. For groups we use @defgroup and @addtogroup. Also,this patch adds some small missing docs. --- diff --git a/src/lib/ecore/Ecore_Common.h b/src/lib/ecore/Ecore_Common.h index f1b11ee..15d92f8 100644 --- a/src/lib/ecore/Ecore_Common.h +++ b/src/lib/ecore/Ecore_Common.h @@ -10,8 +10,8 @@ extern "C" { #include "ecore_input_device.eo.h" /** - * @ingroup Ecore * @defgroup Ecore_Init_Group Ecore initialization, shutdown functions and reset on fork. + * @ingroup Ecore * @{ */ @@ -2674,8 +2674,8 @@ EAPI double ecore_throttle_get(void); */ /** - * @ingroup Ecore_Main_Loop_Group * @defgroup Ecore_Poller_Group Ecore Poll functions + * @ingroup Ecore_Main_Loop_Group * * Ecore poller provides infrastructure for the creation of pollers. Pollers * are, in essence, callbacks that share a single timer per type. Because not diff --git a/src/lib/ecore/Ecore_Eo.h b/src/lib/ecore/Ecore_Eo.h index 48adee4..a15a1c1 100644 --- a/src/lib/ecore/Ecore_Eo.h +++ b/src/lib/ecore/Ecore_Eo.h @@ -9,7 +9,7 @@ extern "C" { #include /** - * @ingroup Ecore_Timer_Group + * @addtogroup Ecore_Timer_Group * * @{ */ @@ -25,7 +25,7 @@ extern "C" { #include "efl_loop_message_future_handler.eo.h" /** - * @ingroup Ecore_MainLoop_Group + * @addtogroup Ecore_MainLoop_Group * * @{ */ @@ -97,7 +97,7 @@ EAPI Eo *efl_main_loop_get(void); */ /** - * @ingroup Ecore_Fd_Io_Group + * @addtogroup Ecore_Fd_Io_Group * * @{ */ @@ -119,7 +119,7 @@ EAPI Eo *efl_main_loop_get(void); */ /** - * @ingroup Ecore_Model_Group + * @addtogroup Ecore_Model_Group * * @{ */ diff --git a/src/lib/ecore/Ecore_Legacy.h b/src/lib/ecore/Ecore_Legacy.h index f6e173d..48221d7 100644 --- a/src/lib/ecore/Ecore_Legacy.h +++ b/src/lib/ecore/Ecore_Legacy.h @@ -6,7 +6,7 @@ extern "C" { #endif /** - * @ingroup Ecore_Poller_Group + * @addtogroup Ecore_Poller_Group * * @{ */ @@ -80,8 +80,6 @@ EAPI double ecore_poller_poll_interval_get(Ecore_Poller_Type type); * @param[in] interval The tick interval; must be a power of 2 and <= 32768. * * @return @c true on success, @c false on failure. - * - * @ingroup Ecore_Poller */ EAPI Eina_Bool ecore_poller_poller_interval_set(Ecore_Poller *obj, int interval); @@ -89,8 +87,6 @@ EAPI Eina_Bool ecore_poller_poller_interval_set(Ecore_Poller *obj, int interval) * @brief Polling interval rate of the poller. * * @return The tick interval; must be a power of 2 and <= 32768. - * - * @ingroup Ecore_Poller */ EAPI int ecore_poller_poller_interval_get(const Ecore_Poller *obj); @@ -99,7 +95,7 @@ EAPI int ecore_poller_poller_interval_get(const Ecore_Poller *obj); */ /** - * @ingroup Ecore_Animator_Group + * @addtogroup Ecore_Animator_Group * * @{ */ @@ -213,7 +209,7 @@ EAPI void ecore_animator_thaw(Ecore_Animator *animator); */ /** - * @ingroup Ecore_Timer_Group + * @addtogroup Ecore_Timer_Group * * @{ */ @@ -318,7 +314,7 @@ EAPI void ecore_timer_thaw(Ecore_Timer *timer); */ /** - * @ingroup Ecore_Idle_Group + * @addtogroup Ecore_Idle_Group * * @{ */ @@ -403,7 +399,7 @@ EAPI void *ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter); */ /** - * @ingroup Ecore_Exe_Group + * @addtogroup Ecore_Exe_Group * * @{ */ @@ -415,7 +411,7 @@ EAPI void *ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter); */ /** - * @ingroup Ecore_Job_Group + * @addtogroup Ecore_Job_Group * * @{ */ diff --git a/src/lib/edje/Edje_Legacy.h b/src/lib/edje/Edje_Legacy.h index 2188b83..84ab387 100644 --- a/src/lib/edje/Edje_Legacy.h +++ b/src/lib/edje/Edje_Legacy.h @@ -464,21 +464,21 @@ EAPI void edje_object_text_change_cb_set(Evas_Object *obj, Edje_Text_Change_Cb f /** - * @ingroup Edje_Object_Communication_Interface_Message + * @addtogroup Edje_Object_Communication_Interface_Message * * @{ */ -typedef struct _Edje_Message_String Edje_Message_String; -typedef struct _Edje_Message_Int Edje_Message_Int; -typedef struct _Edje_Message_Float Edje_Message_Float; -typedef struct _Edje_Message_String_Set Edje_Message_String_Set; -typedef struct _Edje_Message_Int_Set Edje_Message_Int_Set; -typedef struct _Edje_Message_Float_Set Edje_Message_Float_Set; -typedef struct _Edje_Message_String_Int Edje_Message_String_Int; -typedef struct _Edje_Message_String_Float Edje_Message_String_Float; -typedef struct _Edje_Message_String_Int_Set Edje_Message_String_Int_Set; -typedef struct _Edje_Message_String_Float_Set Edje_Message_String_Float_Set; +typedef struct _Edje_Message_String Edje_Message_String; /**< Alias for _Edje_Message_String. */ +typedef struct _Edje_Message_Int Edje_Message_Int; /**< Alias for _Edje_Message_Int */ +typedef struct _Edje_Message_Float Edje_Message_Float; /**< Alias for _Edje_Message_Float */ +typedef struct _Edje_Message_String_Set Edje_Message_String_Set; /**< Alias for _Edje_Message_String_Set */ +typedef struct _Edje_Message_Int_Set Edje_Message_Int_Set; /**< Alias for _Edje_Message_Int_Set */ +typedef struct _Edje_Message_Float_Set Edje_Message_Float_Set; /**< Alias for _Edje_Message_Float_Set */ +typedef struct _Edje_Message_String_Int Edje_Message_String_Int; /**< Alias for _Edje_Message_String_Int */ +typedef struct _Edje_Message_String_Float Edje_Message_String_Float; /**< Alias for _Edje_Message_String_Float */ +typedef struct _Edje_Message_String_Int_Set Edje_Message_String_Int_Set; /**< Alias for _Edje_Message_String_Int_Set */ +typedef struct _Edje_Message_String_Float_Set Edje_Message_String_Float_Set; /**< Alias for _Edje_Message_String_Float_Set */ struct _Edje_Message_String { @@ -657,7 +657,7 @@ EAPI void edje_object_message_signal_recursive_process(Evas_Object *obj); */ /** - * @ingroup Edje_Object + * @addgroup Edje_Object * * @{ */ diff --git a/src/lib/evas/Evas_Common.h b/src/lib/evas/Evas_Common.h index 81581c4..188a2ed 100644 --- a/src/lib/evas/Evas_Common.h +++ b/src/lib/evas/Evas_Common.h @@ -3329,7 +3329,7 @@ EAPI void evas_language_reinit(void); typedef Eo Evas_Out; /** - * @ingroup Evas_Font_Group + * @addtogroup Evas_Font_Group * * @{ */ @@ -3338,8 +3338,6 @@ typedef Eo Evas_Out; * @defgroup Evas_Font_Path_Group Font Path Functions * * Functions that edit the paths being used to load fonts. - * - * @ingroup Evas_Font_Group */ /** diff --git a/src/lib/evas/Evas_Legacy.h b/src/lib/evas/Evas_Legacy.h index 4be9bae..efc4fd8 100755 --- a/src/lib/evas/Evas_Legacy.h +++ b/src/lib/evas/Evas_Legacy.h @@ -141,7 +141,7 @@ typedef unsigned long long Evas_Modifier_Mask; /** - * @ingroup Evas_Canvas_Events + * @addtogroup Evas_Canvas_Events * * @{ */ @@ -1198,7 +1198,7 @@ EAPI void evas_touch_point_list_nth_xy_get(Evas *eo_e, unsigned int n, Evas_Coor */ /** - * @ingroup Evas_Font_Group + * @addtogroup Evas_Font_Group * * @{ */ @@ -1208,14 +1208,10 @@ EAPI void evas_touch_point_list_nth_xy_get(Evas *eo_e, unsigned int n, Evas_Coor * * @param e The evas instance that returned such list. * @param available the list returned by evas_font_dir_available_list(). - * - * @ingroup Evas_Font_Group */ EAPI void evas_font_available_list_free(Evas *e, Eina_List *available) EINA_ARG_NONNULL(1); /** Flags for Font Hinting - * - * @ingroup Evas_Font */ typedef enum { @@ -1231,8 +1227,6 @@ typedef enum * * @param[in] hinting The used hinting, one of #EVAS_FONT_HINTING_NONE, * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE. - * - * @ingroup Evas_Font_Group */ EAPI void evas_font_hinting_set(Evas *e, Evas_Font_Hinting_Flags hinting); @@ -1241,8 +1235,6 @@ EAPI void evas_font_hinting_set(Evas *e, Evas_Font_Hinting_Flags hinting); * * @return The used hinting, one of #EVAS_FONT_HINTING_NONE, * #EVAS_FONT_HINTING_AUTO, #EVAS_FONT_HINTING_BYTECODE. - * - * @ingroup Evas_Font_Group */ EAPI Evas_Font_Hinting_Flags evas_font_hinting_get(const Evas *e); @@ -6449,7 +6441,7 @@ EAPI void evas_object_image_alpha_mask_set(Evas_Object *obj, Eina_Bool ismask) E */ /** - * @ingroup Evas_Object_Text + * @addtogroup Evas_Object_Text * * @{ */ @@ -6723,7 +6715,7 @@ EAPI Evas_Object *evas_object_line_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ARG */ /** - * @ingroup Evas_Object_Polygon + * @addtogroup Evas_Object_Polygon * * @{ */ @@ -6737,15 +6729,13 @@ EAPI Evas_Object *evas_object_polygon_add(Evas *e) EINA_WARN_UNUSED_RESULT EINA_ /** * @brief Adds the given point to the given evas polygon object. * + * @param[in] obj The object * @param[in] y The Y coordinate of the given point. - * - * @ingroup Evas_Polygon */ EAPI void evas_object_polygon_point_add(Evas_Object *obj, Evas_Coord x, Evas_Coord y); /** Removes all of the points from the given evas polygon object. - * - * @ingroup Evas_Polygon + * @param[in] obj The object */ EAPI void evas_object_polygon_points_clear(Evas_Object *obj); @@ -6760,7 +6750,7 @@ EAPI void evas_object_polygon_points_clear(Evas_Object *obj); /** - * @ingroup Evas_Smart_Object_Group + * @addtogroup Evas_Smart_Object_Group * * @{ */ @@ -7235,7 +7225,7 @@ EAPI void evas_object_smart_move_children_relative(Evas_Object *obj, Evas_Coord */ /** - * @ingroup Evas_Object_Box + * @addtogroup Evas_Object_Box * * @{ */ @@ -7371,7 +7361,7 @@ EAPI Eina_List *evas_object_box_children_get(const Evas_Object * */ /** - * @ingroup Evas_Object_Table + * @addtogroup Evas_Object_Table * * @{ */ @@ -7418,7 +7408,7 @@ EAPI Eina_Bool evas_object_table_mirrored_get(const Eo *obj); */ /** - * @ingroup Evas_Object_Grid + * @addtogroup Evas_Object_Grid * * @{ */ diff --git a/src/lib/evas/canvas/evas_textblock_legacy.h b/src/lib/evas/canvas/evas_textblock_legacy.h index bc87e07..e79a0c2 100644 --- a/src/lib/evas/canvas/evas_textblock_legacy.h +++ b/src/lib/evas/canvas/evas_textblock_legacy.h @@ -118,8 +118,7 @@ * @li password - "on" or "off". This is used to specifically turn replacing chars with the replacement char (i.e password mode) on and off. * * @warning We don't guarantee any proper results if you create a Textblock - * object - * without setting the evas engine. + * object without setting the evas engine. * * @todo put here some usage examples * @@ -674,7 +673,7 @@ EAPI Eina_Bool evas_textblock_cursor_word_end(Evas_Textblock_Cursor *obj); */ /** - * @ingroup Evas_Object_Textblock + * @addtogroup Evas_Object_Textblock * * @{ */