Doxygen style comments part 1 - grid/, layout/, view/ etc 14/63214/4
authorAgnieszka Janowicz <a.janowicz@samsung.com>
Tue, 22 Mar 2016 14:35:40 +0000 (15:35 +0100)
committerAgnieszka Janowicz <a.janowicz@samsung.com>
Wed, 23 Mar 2016 14:54:30 +0000 (15:54 +0100)
@TODO: common/ and data/ modules

Change-Id: I8aae1fb0b334007a9d35550c26511ce021930d73
Signed-off-by: Agnieszka Janowicz <a.janowicz@samsung.com>
31 files changed:
include/app_debug.h
include/data/settings_preferences.h
include/grid/grid_location.h
include/grid/grid_sound.h
include/grid/grid_wireless.h
include/layout.h
include/view/common/view_generic_popup.h
include/view/picture/view_picture_brightness.h
include/view/picture/view_picture_color.h
include/view/picture/view_picture_contrast.h
include/view/picture/view_picture_mode.h
include/view/picture/view_picture_screen_adj.h
include/view/picture/view_picture_sharpness.h
include/view/picture/view_picture_slider_generic.h
include/view/picture/view_picture_tint.h
include/view/system/view_clock.h
include/view/system/view_language.h
include/view/system/view_location.h
include/view/system/view_pincode.h
include/view/system/view_reset.h
include/view/system/view_sleep_timer.h
include/view/system/view_subtitle.h
include/view/system/view_wakeup_timer.h
include/view/view_action_menu.h
include/view/view_base.h
include/view_new_network.h
src/grid/grid_sound.c
src/layout/layout_sound.c
src/view/common/view_generic_popup.c
src/view/picture/view_picture_screen_adj.c
src/view/system/view_sleep_timer.c

index b093070..389c4d5 100644 (file)
 #ifndef __AIR_SETTINGS_APP_DEBUG_H__
 #define __AIR_SETTINGS_APP_DEBUG_H__
 
-/* FIXME: debug enalbed */
+/* FIXME: debug enabled */
 #define TIZEN_DEBUG_ENABLE
 #include <dlog.h>
 
-// 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
index f6d1b69..ecf4ce5 100644 (file)
 * @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);
 
index b2afa16..a4b9305 100644 (file)
@@ -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);
 
index bb7b977..eaba8ec 100644 (file)
 
 #include <stdbool.h>
 
+/**
+* @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);
 
index 21a65f3..c412fd1 100644 (file)
@@ -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);
 
index 50d7b8e..dcae6e6 100644 (file)
@@ -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);
 
index d897886..8504025 100644 (file)
 #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);
 
index e1cedb4..9b8d063 100644 (file)
@@ -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);
 
index 2d93e2e..2f4c72e 100644 (file)
@@ -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);
 
index e8cb295..e8382a5 100644 (file)
@@ -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);
 
index 7c293f9..0bfa4d9 100644 (file)
@@ -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);
 
index 0ea16d3..64da3d5 100644 (file)
@@ -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);
 
index fad77cb..3ee6745 100644 (file)
@@ -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);
 
index b8e0a2b..8b48e8e 100644 (file)
@@ -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);
 
index d50b237..3c612da 100644 (file)
@@ -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);
 
index fe90afc..619b597 100644 (file)
@@ -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);
 
index 1ae342b..8b4fcf4 100644 (file)
@@ -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);
 
index 4df9424..d5bb53b 100644 (file)
@@ -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);
 
index a133f2a..878b05b 100644 (file)
@@ -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);
 
index 9f9cbbe..5acb1d3 100644 (file)
@@ -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);
 
index 5638e9e..ab63a24 100644 (file)
@@ -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);
 
index 12c8553..6ed4b3c 100644 (file)
@@ -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);
 
index db6ff5b..357b3af 100644 (file)
@@ -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);
 
index a3084d1..493d45f 100644 (file)
 
 #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);
 
index 7bb7727..fb926fb 100644 (file)
@@ -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);
 
index 904e419..f359142 100644 (file)
@@ -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);
 
index 2fa7e0e..ab73264 100644 (file)
@@ -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;
 }
index e859dd2..789e0fa 100644 (file)
@@ -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))
index c7dc338..dd82a69 100644 (file)
@@ -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");
index 475515e..673072f 100644 (file)
@@ -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;
index 5f28eba..aa2b8b7 100644 (file)
@@ -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;