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 (file)
--- 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 (file)
--- a/src/lib/ecore/Ecore_Eo.h
+++ b/src/lib/ecore/Ecore_Eo.h
@@ -9,7 +9,7 @@ extern "C" {
 #include <Eo.h>
 
 /**
- * @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 (file)
--- 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 (file)
--- 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 (file)
--- 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 (executable)
--- 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 (file)
--- 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
  *
  * @{
  */