From d7bdfe68273b6feb159c3be629c2afcd8e32ad56 Mon Sep 17 00:00:00 2001 From: Agnieszka Janowicz Date: Tue, 22 Mar 2016 15:35:40 +0100 Subject: [PATCH] Doxygen style comments part 1 - grid/, layout/, view/ etc @TODO: common/ and data/ modules Change-Id: I8aae1fb0b334007a9d35550c26511ce021930d73 Signed-off-by: Agnieszka Janowicz --- include/app_debug.h | 19 +++++++--- include/data/settings_preferences.h | 6 ++-- include/grid/grid_location.h | 4 +-- include/grid/grid_sound.h | 13 ++++--- include/grid/grid_wireless.h | 4 +-- include/layout.h | 35 +++++++++--------- include/view/common/view_generic_popup.h | 33 ++++++++++------- include/view/picture/view_picture_brightness.h | 4 +-- include/view/picture/view_picture_color.h | 4 +-- include/view/picture/view_picture_contrast.h | 4 +-- include/view/picture/view_picture_mode.h | 4 +-- include/view/picture/view_picture_screen_adj.h | 4 +-- include/view/picture/view_picture_sharpness.h | 4 +-- include/view/picture/view_picture_slider_generic.h | 42 +++++++++++++--------- include/view/picture/view_picture_tint.h | 4 +-- include/view/system/view_clock.h | 4 +-- include/view/system/view_language.h | 4 +-- include/view/system/view_location.h | 4 +-- include/view/system/view_pincode.h | 4 +-- include/view/system/view_reset.h | 4 +-- include/view/system/view_sleep_timer.h | 4 +-- include/view/system/view_subtitle.h | 4 +-- include/view/system/view_wakeup_timer.h | 4 +-- include/view/view_action_menu.h | 28 +++++++++++---- include/view/view_base.h | 4 +-- include/view_new_network.h | 4 +-- src/grid/grid_sound.c | 2 +- src/layout/layout_sound.c | 6 ++-- src/view/common/view_generic_popup.c | 2 +- src/view/picture/view_picture_screen_adj.c | 2 +- src/view/system/view_sleep_timer.c | 2 +- 31 files changed, 157 insertions(+), 109 deletions(-) diff --git a/include/app_debug.h b/include/app_debug.h index b093070..389c4d5 100644 --- a/include/app_debug.h +++ b/include/app_debug.h @@ -17,26 +17,37 @@ #ifndef __AIR_SETTINGS_APP_DEBUG_H__ #define __AIR_SETTINGS_APP_DEBUG_H__ -/* FIXME: debug enalbed */ +/* FIXME: debug enabled */ #define TIZEN_DEBUG_ENABLE #include -// added to solve problem with double dlog texts, also helpfull to see how long does it take /** -* @brief +* @brief Get the current time of the clock in nanoseconds. * -* @return +* Added to solve problems with double dlog texts, +* also helpful to see how long functions take to execute. +* +* @return The current time in nanoseconds. */ extern long int _timens(); +/** +* @brief A convenience macro for logging at the error level. +*/ #ifndef _ERR #define _ERR(fmt, args...) LOGE("[%ld] "fmt"\n", _timens(), ##args) #endif +/** +* @brief A convenience macro for logging at the debug level. +*/ #ifndef _DBG #define _DBG(fmt, args...) LOGD("[%ld] "fmt"\n", _timens(), ##args) #endif +/** +* @brief A convenience macro for logging at the info level. +*/ #ifndef _INFO #define _INFO(fmt, args...) LOGI("[%ld] "fmt"\n", _timens(), ##args) #endif diff --git a/include/data/settings_preferences.h b/include/data/settings_preferences.h index f6d1b69..ecf4ce5 100644 --- a/include/data/settings_preferences.h +++ b/include/data/settings_preferences.h @@ -23,17 +23,17 @@ * @param tab_index * @param ret_value * -* @return +* @return */ bool settings_preferences_tab_order_get(int tab_index, char **ret_value); /** -* @brief +* @brief * * @param tab_index * @param new_value * -* @return +* @return */ bool settings_preferences_tab_order_set(int tab_index, const char *new_value); diff --git a/include/grid/grid_location.h b/include/grid/grid_location.h index b2afa16..a4b9305 100644 --- a/include/grid/grid_location.h +++ b/include/grid/grid_location.h @@ -18,9 +18,9 @@ #define __AIR_SETTINGS_GRID_LOCATION_H__ /** -* @brief +* @brief Get the pointer to the grid_class object of location grid. * -* @return +* @return The pointer to location grid_class object. */ struct grid_class *get_location_grid_class(void); diff --git a/include/grid/grid_sound.h b/include/grid/grid_sound.h index bb7b977..eaba8ec 100644 --- a/include/grid/grid_sound.h +++ b/include/grid/grid_sound.h @@ -19,16 +19,19 @@ #include +/** +* @brief Sound grid item's data. +*/ struct sound_item_s { - char *label; - int id; - bool enabled; + char *label; /**< item's label */ + int id; /**< item's ID */ + bool selected; /**< item's selected state */ }; /** -* @brief +* @brief Get the pointer to the grid_class object of sound grid. * -* @return +* @return The pointer to sound grid_class object. */ struct grid_class *get_sound_grid_class(void); diff --git a/include/grid/grid_wireless.h b/include/grid/grid_wireless.h index 21a65f3..c412fd1 100644 --- a/include/grid/grid_wireless.h +++ b/include/grid/grid_wireless.h @@ -18,9 +18,9 @@ #define __AIR_SETTINGS_GRID_WIRELESS_H__ /** -* @brief +* @brief Get the pointer to the grid_class object of wireless grid. * -* @return +* @return The pointer to wireless grid_class object. */ struct grid_class *get_wireless_grid_class(void); diff --git a/include/layout.h b/include/layout.h index 50d7b8e..dcae6e6 100644 --- a/include/layout.h +++ b/include/layout.h @@ -22,6 +22,9 @@ /*release changes:*/ #define LAYOUT_MAX 2 +/** +* @brief Available layout types. +*/ enum layout_type { LAYOUT_PICTURE = 0, LAYOUT_SOUND, @@ -35,58 +38,58 @@ enum layout_type { }; /** -* @brief +* @brief Get the pointer to the layout_class object of picture layout. * -* @return +* @return The pointer to picture layout_class object. */ layout_class *layout_picture_get_lclass(void); /** -* @brief +* @brief Get the pointer to the layout_class object of sound layout. * -* @return +* @return The pointer to sound layout_class object. */ layout_class *layout_sound_get_lclass(void); /** -* @brief +* @brief Get the pointer to the layout_class object of channel layout. * -* @return +* @return The pointer to channel layout_class object. */ layout_class *layout_channel_get_lclass(void); /** -* @brief +* @brief Get the pointer to the layout_class object of network layout. * -* @return +* @return The pointer to network layout_class object. */ layout_class *layout_network_get_lclass(void); /** -* @brief +* @brief Get the pointer to the layout_class object of system layout. * -* @return +* @return The pointer to system layout_class object. */ layout_class *layout_system_get_lclass(void); /** -* @brief +* @brief Get the pointer to the layout_class object of support layout. * -* @return +* @return The pointer to support layout_class object. */ layout_class *layout_support_get_lclass(void); /** -* @brief +* @brief Get the pointer to the layout_class object of info layout. * -* @return +* @return The pointer to info layout_class object. */ layout_class *layout_info_get_lclass(void); /** -* @brief +* @brief Get the pointer to the layout_class object of voice layout. * -* @return +* @return The pointer to voice layout_class object. */ layout_class *layout_voice_get_lclass(void); diff --git a/include/view/common/view_generic_popup.h b/include/view/common/view_generic_popup.h index d897886..8504025 100644 --- a/include/view/common/view_generic_popup.h +++ b/include/view/common/view_generic_popup.h @@ -21,26 +21,35 @@ #include "common/inputmgr.h" /*TODO: make use of it and add more types if necessary:*/ + +/** +* @brief Available types of generic popups. +*/ typedef enum { POPUP_TYPE_BUTTONS_LIST = 0 -}popup_type_t; +} popup_type_t; +/** +* @brief Attributes of a generic popup view. +*/ typedef struct { - const char *popup_title; /* in */ - const char *popup_description; /* in */ - const char *popup_layout_group; /* in */ - input_handler *handler; /* in */ - int buttns_count; /* in - valid for popup with buttons only */ - const char **btn_texts; /* in - valid for popup with buttons only */ - int (*ui_id_on_show_focus)(void); /* in */ - void *generic_popup_data; /* out - to be used by inheriting class */ -} generic_popup_parameter; + const char *popup_title; /**< popup's title */ + const char *popup_description; /**< popup's description */ + const char *popup_layout_group; /**< popup's layout view */ + input_handler *handler; /**< popup's input handler */ + int buttns_count; /**< popup's buttons count - valid for popups with buttons only */ + const char **btn_texts; /**< labels to be set on popup's buttons - valid for popup with buttons only */ + int (*ui_id_on_show_focus)(void); /**< callback function to be invoked when popup is shown; + * returns ID of the widget that should receive focus first. + */ + void *generic_popup_data; /**< [out] popup view's data - to be used by inheriting class */ +} generic_popup_attr; /** -* @brief +* @brief Get the pointer to the view_class object of generic popup view. * -* @return +* @return The pointer to generic popup view_class object. */ view_class *view_generic_popup_get_vclass(void); diff --git a/include/view/picture/view_picture_brightness.h b/include/view/picture/view_picture_brightness.h index e1cedb4..9b8d063 100644 --- a/include/view/picture/view_picture_brightness.h +++ b/include/view/picture/view_picture_brightness.h @@ -20,9 +20,9 @@ #include "common/viewmgr.h" /** -* @brief +* @brief Get the pointer to the view_class object of picture brightness view. * -* @return +* @return The pointer to picture brightness view_class object. */ view_class *view_picture_brightness_get_vclass(void); diff --git a/include/view/picture/view_picture_color.h b/include/view/picture/view_picture_color.h index 2d93e2e..2f4c72e 100644 --- a/include/view/picture/view_picture_color.h +++ b/include/view/picture/view_picture_color.h @@ -20,9 +20,9 @@ #include "common/viewmgr.h" /** -* @brief +* @brief Get the pointer to the view_class object of picture color view. * -* @return +* @return The pointer to picture color view_class object. */ view_class *view_picture_color_get_vclass(void); diff --git a/include/view/picture/view_picture_contrast.h b/include/view/picture/view_picture_contrast.h index e8cb295..e8382a5 100644 --- a/include/view/picture/view_picture_contrast.h +++ b/include/view/picture/view_picture_contrast.h @@ -20,9 +20,9 @@ #include "common/viewmgr.h" /** -* @brief +* @brief Get the pointer to the view_class object of picture contrast view. * -* @return +* @return The pointer to picture contrast view_class object. */ view_class *view_picture_contrast_get_vclass(void); diff --git a/include/view/picture/view_picture_mode.h b/include/view/picture/view_picture_mode.h index 7c293f9..0bfa4d9 100644 --- a/include/view/picture/view_picture_mode.h +++ b/include/view/picture/view_picture_mode.h @@ -20,9 +20,9 @@ #include "common/viewmgr.h" /** -* @brief +* @brief Get the pointer to the view_class object of picture mode view. * -* @return +* @return The pointer to picture mode view_class object. */ view_class *view_picture_mode_get_vclass(void); diff --git a/include/view/picture/view_picture_screen_adj.h b/include/view/picture/view_picture_screen_adj.h index 0ea16d3..64da3d5 100644 --- a/include/view/picture/view_picture_screen_adj.h +++ b/include/view/picture/view_picture_screen_adj.h @@ -20,9 +20,9 @@ #include "view/common/view_generic_popup.h" /** -* @brief +* @brief Get the pointer to the view_class object of picture screen adjustment view. * -* @return +* @return The pointer to picture screen adjustment view_class object. */ view_class *view_picture_screen_adj_get_vclass(void); diff --git a/include/view/picture/view_picture_sharpness.h b/include/view/picture/view_picture_sharpness.h index fad77cb..3ee6745 100644 --- a/include/view/picture/view_picture_sharpness.h +++ b/include/view/picture/view_picture_sharpness.h @@ -20,9 +20,9 @@ #include "common/viewmgr.h" /** -* @brief +* @brief Get the pointer to the view_class object of picture sharpness view. * -* @return +* @return The pointer to picture sharpness view_class object. */ view_class *view_picture_sharpness_get_vclass(void); diff --git a/include/view/picture/view_picture_slider_generic.h b/include/view/picture/view_picture_slider_generic.h index b8e0a2b..8b48e8e 100644 --- a/include/view/picture/view_picture_slider_generic.h +++ b/include/view/picture/view_picture_slider_generic.h @@ -25,28 +25,36 @@ typedef void (*set_value)(int val); typedef int (*get_value)(void); typedef void (*get_str)(int val, char *out_str); +/** +* @brief Attributes of a generic slider view. +*/ typedef struct { - const char *slider_title; - - int slider_min_val; - int slider_max_val; - int slider_cur_val; - double slider_step; - - const char *slider_min_str; - const char *slider_max_str; - - set_value set_setting_value; - get_value get_setting_value; - get_str get_setting_str; - - void *generic_slider_data; + const char *slider_title; /**< slider view's title */ + + int slider_min_val; /**< minimum value of the slider */ + int slider_max_val; /**< maximum value of the slider */ + int slider_cur_val; /**< current value of the slider */ + double slider_step; /**< step of the slider (resolution) */ + + const char *slider_min_str; /**< minimum slider value string (to be placed + * under the end of slider associated with the minimum value) */ + const char *slider_max_str; /**< maximum slider value string (to be placed + * under the end of slider associated with the maximum value) */ + + set_value set_setting_value; /**< function for setting the global setting + * associated with the slider to current slider's value */ + get_value get_setting_value; /**< function for getting the global setting + * associated with the slider */ + get_str get_setting_str; /**< function for getting the global setting associated with the slider + *in text format. Use only if the text should different than numeric value only. */ + + void *generic_slider_data; /**< [out] slider view's data - to be used by inheriting class */ } generic_slider_attr; /** -* @brief +* @brief Get the pointer to the view_class object of generic picture slider view. * -* @return +* @return The pointer to generic picture slider view_class object. */ view_class *view_picture_slider_generic_get_vclass(void); diff --git a/include/view/picture/view_picture_tint.h b/include/view/picture/view_picture_tint.h index d50b237..3c612da 100644 --- a/include/view/picture/view_picture_tint.h +++ b/include/view/picture/view_picture_tint.h @@ -20,9 +20,9 @@ #include "common/viewmgr.h" /** -* @brief +* @brief Get the pointer to the view_class object of picture tint view. * -* @return +* @return The pointer to picture tint view_class object. */ view_class *view_picture_tint_get_vclass(void); diff --git a/include/view/system/view_clock.h b/include/view/system/view_clock.h index fe90afc..619b597 100644 --- a/include/view/system/view_clock.h +++ b/include/view/system/view_clock.h @@ -18,9 +18,9 @@ #define __AIR_SETTINGS_VIEW_CLOCK_H__ /** -* @brief +* @brief Get the pointer to the view_class object of clock view. * -* @return +* @return The pointer to clock view_class object. */ view_class *view_clock_get_vclass(void); diff --git a/include/view/system/view_language.h b/include/view/system/view_language.h index 1ae342b..8b4fcf4 100644 --- a/include/view/system/view_language.h +++ b/include/view/system/view_language.h @@ -18,9 +18,9 @@ #define __AIR_SETTINGS_VIEW_LANGUAGE_H__ /** -* @brief +* @brief Get the pointer to the view_class object of language view. * -* @return +* @return The pointer to language view_class object. */ view_class *view_language_get_vclass(void); diff --git a/include/view/system/view_location.h b/include/view/system/view_location.h index 4df9424..d5bb53b 100644 --- a/include/view/system/view_location.h +++ b/include/view/system/view_location.h @@ -18,9 +18,9 @@ #define __AIR_SETTINGS_VIEW_LOCATION_H__ /** -* @brief +* @brief Get the pointer to the view_class object of location view. * -* @return +* @return The pointer to location view_class object. */ view_class *view_location_get_vclass(void); diff --git a/include/view/system/view_pincode.h b/include/view/system/view_pincode.h index a133f2a..878b05b 100644 --- a/include/view/system/view_pincode.h +++ b/include/view/system/view_pincode.h @@ -20,9 +20,9 @@ #include "common/viewmgr.h" /** -* @brief +* @brief Get the pointer to the view_class object of pincode view. * -* @return +* @return The pointer to pincode view_class object. */ view_class *view_pincode_get_vclass(void); diff --git a/include/view/system/view_reset.h b/include/view/system/view_reset.h index 9f9cbbe..5acb1d3 100644 --- a/include/view/system/view_reset.h +++ b/include/view/system/view_reset.h @@ -18,9 +18,9 @@ #define __AIR_SETTINGS_VIEW_RESET_H__ /** -* @brief +* @brief Get the pointer to the view_class object of reset view. * -* @return +* @return The pointer to reset view_class object. */ view_class *view_reset_get_vclass(void); diff --git a/include/view/system/view_sleep_timer.h b/include/view/system/view_sleep_timer.h index 5638e9e..ab63a24 100644 --- a/include/view/system/view_sleep_timer.h +++ b/include/view/system/view_sleep_timer.h @@ -18,9 +18,9 @@ #define __AIR_SETTINGS_VIEW_SLEEP_TIMER_H__ /** -* @brief +* @brief Get the pointer to the view_class object of sleep timer view. * -* @return +* @return The pointer to sleep timer view_class object. */ view_class *view_sleep_timer_get_vclass(void); diff --git a/include/view/system/view_subtitle.h b/include/view/system/view_subtitle.h index 12c8553..6ed4b3c 100644 --- a/include/view/system/view_subtitle.h +++ b/include/view/system/view_subtitle.h @@ -18,9 +18,9 @@ #define __AIR_SETTINGS_VIEW_SUBTITLE_H__ /** -* @brief +* @brief Get the pointer to the view_class object of subtitles view. * -* @return +* @return The pointer to subtitles view_class object. */ view_class *view_subtitle_get_vclass(void); diff --git a/include/view/system/view_wakeup_timer.h b/include/view/system/view_wakeup_timer.h index db6ff5b..357b3af 100644 --- a/include/view/system/view_wakeup_timer.h +++ b/include/view/system/view_wakeup_timer.h @@ -18,9 +18,9 @@ #define __AIR_SETTINGS_VIEW_WAKEUP_TIMER_H__ /** -* @brief +* @brief Get the pointer to the view_class object of wakeup timer view. * -* @return +* @return The pointer to wakeup timer view_class object. */ view_class *view_wakeup_timer_get_vclass(void); diff --git a/include/view/view_action_menu.h b/include/view/view_action_menu.h index a3084d1..493d45f 100644 --- a/include/view/view_action_menu.h +++ b/include/view/view_action_menu.h @@ -19,21 +19,35 @@ #include "common/viewmgr.h" +/** +* @brief Attributes of the action menu view. +* +* As action menu layout differs depending on the currently focused object, +* the parameters in the form of this structure need to be passed to the action menu view +* each time it is to be updated. +*/ typedef struct { + const char *layout_id; /**< ID of the displayed layout corresponding to + * the currently focused menu tab, or NULL + * if the layout's subitem has focus */ + const char *layout_subitem_id; /**< ID of currently focused layout's item, or NULL + * if the current menu tab has focus */ + int layout_subitem_menu_id; /** < numerical ID of the currently focused layout's + * item or of the displayed layout corresponding to + * the currently focused menu tab */ +} action_menu_parameter; - const char *layout_id; - const char *layout_subitem_id; - int layout_subitem_menu_id; -}action_menu_parameter; - +/** +* @brief Available update types for action menu view. +*/ enum { ACT_MENU_SRC_VIEW_UPDATE }; /** -* @brief +* @brief Get the pointer to the view_class object of action menu view. * -* @return +* @return The pointer to action menu view_class object. */ view_class *view_action_menu_get_vclass(void); diff --git a/include/view/view_base.h b/include/view/view_base.h index 7bb7727..fb926fb 100644 --- a/include/view/view_base.h +++ b/include/view/view_base.h @@ -18,9 +18,9 @@ #define __AIR_SETTINGS_VIEW_BASE_H__ /** -* @brief +* @brief Get the pointer to the view_class object of base view. * -* @return +* @return The pointer to base view_class object. */ view_class *view_base_get_vclass(void); diff --git a/include/view_new_network.h b/include/view_new_network.h index 904e419..f359142 100644 --- a/include/view_new_network.h +++ b/include/view_new_network.h @@ -18,9 +18,9 @@ #define __AIR_SETTINGS_VIEW_NEW_NETWORK_H__ /** -* @brief +* @brief Get the pointer to the view_class object of new network view. * -* @return +* @return The pointer to new network view_class object. */ view_class *view_new_network_get_vclass(void); diff --git a/src/grid/grid_sound.c b/src/grid/grid_sound.c index 2fa7e0e..ab73264 100644 --- a/src/grid/grid_sound.c +++ b/src/grid/grid_sound.c @@ -63,5 +63,5 @@ static Eina_Bool _state_get_cb(void *data, Evas_Object *obj, const char *part) return EINA_FALSE; } - return s_info->enabled; + return s_info->selected; } diff --git a/src/layout/layout_sound.c b/src/layout/layout_sound.c index e859dd2..789e0fa 100644 --- a/src/layout/layout_sound.c +++ b/src/layout/layout_sound.c @@ -315,11 +315,11 @@ static bool _select_item(Elm_Object_Item *it, struct _priv *priv, return false; } - if (!item_info->enabled) { - item_info->enabled = true; + if (!item_info->selected) { + item_info->selected = true; if (prev_it) { item_info = (struct sound_item_s *)elm_object_item_data_get(prev_it); - item_info->enabled = false; + item_info->selected = false; } if (!listmgr_update_grid(priv->list_mgr, list_id)) diff --git a/src/view/common/view_generic_popup.c b/src/view/common/view_generic_popup.c index c7dc338..dd82a69 100644 --- a/src/view/common/view_generic_popup.c +++ b/src/view/common/view_generic_popup.c @@ -61,7 +61,7 @@ view_class *view_generic_popup_get_vclass(void) static Evas_Object *_create(Evas_Object *win, void *data) { struct _priv *priv = NULL; - generic_popup_parameter *g_data = (generic_popup_parameter *)data; + generic_popup_attr *g_data = (generic_popup_attr *)data; if (!win || !g_data) { _ERR("Invalid arguments"); diff --git a/src/view/picture/view_picture_screen_adj.c b/src/view/picture/view_picture_screen_adj.c index 475515e..673072f 100644 --- a/src/view/picture/view_picture_screen_adj.c +++ b/src/view/picture/view_picture_screen_adj.c @@ -66,7 +66,7 @@ view_class *view_picture_screen_adj_get_vclass(void) static Evas_Object *_create(Evas_Object *win, void *data) { struct _priv *priv = NULL; - generic_popup_parameter constructor_param = {0,}; + generic_popup_attr constructor_param = {0,}; constructor_param.buttns_count = SCREEN_ADJ_OPTS_COUNT; constructor_param.popup_title = title; diff --git a/src/view/system/view_sleep_timer.c b/src/view/system/view_sleep_timer.c index 5f28eba..aa2b8b7 100644 --- a/src/view/system/view_sleep_timer.c +++ b/src/view/system/view_sleep_timer.c @@ -63,7 +63,7 @@ static input_handler handler = { static Evas_Object *_create(Evas_Object *win, void *data) { struct _priv *priv = NULL; - generic_popup_parameter constructor_param = {0,}; + generic_popup_attr constructor_param = {0,}; constructor_param.buttns_count = POPUP_SLEEP_TIMER_BTN_COUNT; constructor_param.popup_title = STR_SLEEP_TIMER; -- 2.7.4