Doxygen style comments - common/

Change-Id: I7c83ff1415ad70e6cff9a908621bb5adfdb2633b
Signed-off-by: Radek Kintop <r.kintop@samsung.com>

diff --git a/include/common/datamgr.h b/include/common/datamgr.h
index b43f14f..801da76 100644 (file)
--- a/include/common/datamgr.h
+++ b/include/common/datamgr.h
@@ -40,53 +40,53 @@ struct data_class {
 };
 
 /**
-* @brief 
+* @brief Creates the data manager.
 *
-* @param dclass
-* @param event_cb
-* @param cb_data
+* @param[in] dclass Data class object containing lifecycle callbacks.
+* @param[in] event_cb Data manger event_cb called whenever data model specific event occurs.
+* @param[in] cb_data The event_cb data.
 *
-* @return 
+* @return Pointer to created data manager.
 */
 struct datamgr *datamgr_create(struct data_class *dclass,
                void (*event_cb)(enum event_type type, void *data),
                void *cb_data);
 
 /**
-* @brief 
+* @brief Destroys data manager and frees its resources.
 *
-* @param dmgr
+* @param[in] dmgr Data manager pointer.
 *
-* @return 
+* @return True on success, false otherwise.
 */
 bool datamgr_destroy(struct datamgr *dmgr);
 
 /**
-* @brief 
+* @brief Call it whenever it is necessary to update view associated with model data.
 *
-* @param dmgr
+* @param[in] dmgr Data manager pointer.
 *
-* @return 
+* @return true on success.
 */
 bool datamgr_update(struct datamgr *dmgr);
 
 /**
-* @brief 
+* @brief Call it when associated UI item was selected.
 *
-* @param dmgr
-* @param it
-* @param data
+* @param[in] dmgr Data manager pointer.
+* @param[in] it The selected UI item pointer.
+* @param[in] data passed to data manager class select callback.
 *
-* @return 
+* @return true on success.
 */
 bool datamgr_select(struct datamgr *dmgr, Elm_Object_Item *it, void *data);
 
 /**
-* @brief 
+* @brief Call it whenever you need data list associated with the class.
 *
-* @param dmgr
+* @param[in] dmgr Data manager pointer.
 *
-* @return 
+* @return List of items within the class.
 */
 Eina_List *datamgr_get_data(struct datamgr *dmgr);
 

diff --git a/include/common/favoritemgr.h b/include/common/favoritemgr.h
index a37042c..64391fe 100644 (file)
--- a/include/common/favoritemgr.h
+++ b/include/common/favoritemgr.h
@@ -18,10 +18,10 @@
 #define __AIR_SETTINGS_FAVORITEMGR_H__
 
 /**
-* @brief 
+* @brief Sets the favorite star on or off on the object.
 *
-* @param obj
-* @param status
+* @param[in] obj The object to set the favorite star on or off on.
+* @param[in] status EINA_TRUE if you want to set object as favorite.
 */
 void set_favorite(Evas_Object *obj, Eina_Bool status);
 

diff --git a/include/common/listmgr.h b/include/common/listmgr.h
index fd0e0c2..3e24362 100644 (file)
--- a/include/common/listmgr.h
+++ b/include/common/listmgr.h
@@ -23,33 +23,34 @@
 struct listmgr;
 
 /**
-* @brief 
+* @brief Creates list manager
 *
-* @param parent
+* @param[in] parent The parent layout containing the options to select from.
 *
-* @return 
+* @return List manager pointer. NULL on failure.
 */
 struct listmgr *listmgr_create(Evas_Object *parent);
 
 /**
-* @brief 
+* @brief Destroys list manager and its resources.
 *
-* @param listmgr
+* @param[in] listmgr A list manager pointer.
 *
-* @return 
+* @return True on success, false otherwise.
 */
 bool listmgr_destroy(struct listmgr *listmgr);
 
 /**
-* @brief 
+* @brief Adds a new list to be managed by list manager and internally creates
+* gengrid representing list item options.
 *
-* @param listmgr
-* @param list_id
-* @param gclass
-* @param selected_cb
-* @param cb_data
+* @param[in] listmgr A list manager pointer.
+* @param[in] list_id Unique new list identifier.
+* @param[in] gclass Internal grid class.
+* @param[in] selected_cb Callback called every time a gengrid item is selected.
+* @param[in] cb_data A data to be passed to selected_cb callback
 *
-* @return 
+* @return True on success, false otherwise.
 */
 bool listmgr_add_list(struct listmgr *listmgr, const char *list_id,
                struct grid_class *gclass,
@@ -57,50 +58,50 @@ bool listmgr_add_list(struct listmgr *listmgr, const char *list_id,
                void *cb_data);
 
 /**
-* @brief 
+* @brief Removes list from manager and destroys internal grid.
 *
-* @param listmgr
-* @param list_id
+* @param[in] listmgr A list manager pointer.
+* @param[in] list_id Unique existing list identifier.
 *
-* @return 
+* @return True on success, false otherwise.
 */
 bool listmgr_remove_list(struct listmgr *listmgr, const char *list_id);
 
 /**
-* @brief 
+* @brief Fills the internal grid with new UI list options.
 *
-* @param listmgr
-* @param list_id
-* @param list
-* @param get_item
+* @param[in] listmgr A list manager pointer.
+* @param[in] list_id Unique existing list identifier.
+* @param[in] list List of items data(ids).
+* @param[in] get_item Id of UI item to be selected initially.
 * @param item_returned
 *
-* @return 
+* @return True on success, false otherwise.
 */
 bool listmgr_fill_grid(struct listmgr *listmgr, const char *list_id,
                Eina_List *list, void *get_item, Elm_Object_Item **item_returned);
 
 /**
-* @brief 
+* @brief Shows the internal grid associated with the list.
 *
-* @param listmgr
-* @param list_id
-* @param part
-* @param select_item
+* @param[in] listmgr A list manager pointer.
+* @param[in] list_id Unique existing list identifier.
+* @param[in] part The internal layout part you want the internal grid to be set to and shown.
+* @param[in] select_item The item you want to be selected once the internal grid is shown.
 *
-* @return 
+* @return True on success, false otherwise.
 */
 bool listmgr_show_grid(struct listmgr *listmgr, const char *list_id,
                const char *part, Elm_Object_Item *select_item);
 
 /**
-* @brief 
+* @brief Hides the internal grid associated with the list.
 *
-* @param listmgr
-* @param list_id
-* @param part
+* @param listmgr A list manager pointer.
+* @param list_id Unique existing list identifier.
+* @param part The internal layout part you want the internal grid to be unset from and hidden.
 *
-* @return 
+* @return True on success, false otherwise.
 */
 bool listmgr_hide_grid(struct listmgr *listmgr, const char *list_id,
                const char *part);
@@ -121,32 +122,32 @@ void listmgr_set_list_next_focus(struct listmgr *listmgr, const char *list_id,
                Eina_Bool add_reverse_link, Elm_Focus_Direction reverse_dir);
 
 /**
-* @brief 
+* @brief Updates all items in the grid associated with given list id.
 *
-* @param listmgr
-* @param list_id
+* @param listmgr A list manager pointer.
+* @param list_id Unique existing list identifier.
 *
 * @return 
 */
 bool listmgr_update_grid(struct listmgr *listmgr, const char *list_id);
 
 /**
-* @brief 
+* @brief Adds callbacks to the internal grid object associated with a list.
 *
-* @param listmgr
-* @param list_id
-* @param handler
-* @param data
+* @param listmgr A list manager pointer.
+* @param list_id Unique existing list identifier.
+* @param handler A handler containing grid significant callbacks.
+* @param data Data to be passed to the handler callbacks.
 */
 void listmgr_add_inner_grid_cb(struct listmgr *listmgr, const char *list_id,
                input_handler *handler, void *data);
 
 /**
-* @brief 
+* @brief  Removes callbacks to the internal grid object associated with a list.
 *
-* @param listmgr
-* @param list_id
-* @param handler
+* @param listmgr A list manager pointer.
+* @param list_id Unique existing list identifier.
+* @param handler A handler containing grid significant callbacks.
 */
 void listmgr_remove_inner_grid_cb(struct listmgr *listmgr, const char *list_id,
                input_handler *handler);

diff --git a/include/common/menumgr.h b/include/common/menumgr.h
index b5d672e..6960286 100644 (file)
--- a/include/common/menumgr.h
+++ b/include/common/menumgr.h
@@ -40,30 +40,30 @@ struct menumgr_info {
 };
 
 /**
-* @brief 
+* @brief Creates a menu manager.
 *
-* @param table
-* @param tab_menu_btn
-* @param info
-* @param len
-* @param data
+* @param[in] table Table UI container to be managed by the manager.
+* @param[in] tab_menu_btn External UI element to focus on after table looses its focus.
+* @param[in] info Array of information structures containing menu buttons callbacks, etc.
+* @param[in] len Info array length.
+* @param[in] data Data pointer to be associated with the menu.
 *
-* @return 
+* @return menu manager pointer.
 */
 struct menumgr *menumgr_create(Evas_Object *table, Evas_Object *tab_menu_btn,
                struct menumgr_info *info, int len, void *data);
 
 /**
-* @brief 
+* @brief Destroys a menu manager.
 *
-* @param m
+* @param[in] m Menu manager pointer.
 */
 void menumgr_destroy(struct menumgr *m);
 
 /**
-* @brief 
+* @brief Updates a Menu manager.
 *
-* @param m
+* @param[in] m Menu manager pointer.
 */
 void menumgr_update(struct menumgr *m);
 

diff --git a/include/common/utils.h b/include/common/utils.h
index 8e9bdc8..fef2b5f 100644 (file)
--- a/include/common/utils.h
+++ b/include/common/utils.h
@@ -21,182 +21,182 @@
 #define PART_POPUP_BUTTON_STR_MAX_L 24
 
 /**
-* @brief 
+* @brief Creates elm_layout.
 *
-* @param parent
-* @param group
-* @param win_resize
+* @param[in] parent The layout parent.
+* @param[in] group The edje group name to be used as layout.
+* @param[in] win_resize Whether layout should resize to its parent dimensions.
 *
-* @return 
+* @return Pointer to created elm_layout object.
 */
 Evas_Object *utils_add_layout(Evas_Object *parent, const char *group,
                Eina_Bool win_resize);
 
 /**
-* @brief 
+* @brief Creates elm_box container.
 *
-* @param parent
-* @param part
-* @param horizontal
-* @param pad_h
-* @param pad_v
+* @param[in] parent The box parent.
+* @param[in] part The parent layout part name this box should be set in. Can be NULL.
+* @param[in] horizontal EINA_TRUE if the box should arrange its items horizontally.
+* @param[in] pad_h Horizontal padding between items.
+* @param[in] pad_v Vertical padding between items.
 *
-* @return 
+* @return Pointer to created elm_box object.
 */
 Evas_Object *utils_add_box(Evas_Object *parent, const char *part,
                Eina_Bool horizontal, int pad_h, int pad_v);
 
 /**
-* @brief 
+* @brief Creates elm_button widget.
 *
-* @param parent
-* @param part
-* @param style
-* @param text
+* @param[in] parent The button parent.
+* @param[in] part The parent layout part name this button should be set in. Can be NULL.
+* @param[in] style The button style.
+* @param[in] text The button text.
 *
-* @return 
+* @return Pointer to created elm_button object.
 */
 Evas_Object *utils_add_button(Evas_Object *parent, const char *part,
                const char *style, const char *text);
 
 /**
-* @brief 
+* @brief Creates elm_progressbar.
 *
-* @param parent
-* @param part
-* @param style
+* @param[in] parent The progress parent.
+* @param[in] part The parent layout part name this progress should be set in. Can be NULL.
+* @param[in] style The progress style.
 *
-* @return 
+* @return Pointer to created elm_progressbar object.
 */
 Evas_Object *utils_add_progressbar(Evas_Object *parent, const char *part,
                const char *style);
 
 /**
-* @brief 
+* @brief Creates elm_popup.
 *
-* @param parent
-* @param style
-* @param popup_title
-* @param popup_text
+* @param[in] parent The popup parent.
+* @param[in] style The popup style.
+* @param[in] popup_title The popup title text.
+* @param[in] popup_text The popup text.
 *
-* @return 
+* @return Pointer to created elm_popup object.
 */
 Evas_Object *utils_add_popup(Evas_Object *parent, const char *style,
                const char *popup_title, const char *popup_text);
 
 /**
-* @brief 
+* @brief Creates elm_table.
 *
-* @param parent
-* @param padding_x
-* @param padding_y
+* @param[in] parent The table parent.
+* @param[in] padding_x The table cells horizontal padding.
+* @param[in] padding_y The table cells vertical padding.
 *
-* @return 
+* @return Pointer to created elm_table object.
 */
 Evas_Object *utils_add_table(Evas_Object *parent, int padding_x, int padding_y);
 
 /**
-* @brief 
+* @brief Creates elm_ctxpopup.
 *
-* @param parent
-* @param opt_size
-* @param opt_id
-* @param opt_text
-* @param opt_handler
-* @param data
-* @param selected
+* @param[in] parent The ctxpopup parent.
+* @param[in] opt_size The number of option buttons to select from.
+* @param[in] opt_id Buttons ids array.
+* @param[in] opt_text Buttons names array.
+* @param[in] opt_handler Button callbacks handler.
+* @param[in] data Data to be passed to input callbacks handler.
+* @param[in] selected The index (with regards to ids array) of the button item to be initially selected.
 *
-* @return 
+* @return Pointer to created elm_ctxpopup object.
 */
 Evas_Object *utils_add_ctxpopup(Evas_Object *parent, int opt_size, int *opt_id,
                const char **opt_text, void *opt_handler, void *data, int selected);
 
 /**
-* @brief 
+* @brief Creates elm_gengrid container.
 *
-* @param parent
-* @param horizontal
-* @param width
-* @param height
+* @param[in] parent The gengrid parent.
+* @param[in] horizontal  EINA_TRUE if the gengrid should arrange its items horizontally.
+* @param[in] width Item width.
+* @param[in] height Item height.
 *
-* @return 
+* @return Pointer to created elm_gengrid object.
 */
 Evas_Object *utils_add_gengrid(Evas_Object *parent, Eina_Bool horizontal,
                int width, int height);
 
 /**
-* @brief 
+* @brief Creates elm_entry widget.
 *
-* @param parent
-* @param part
-* @param text_style
-* @param is_password
+* @param[in] parent The entry parent.
+* @param[in] part The parent layout part name this entry should be set in. Can be NULL.
+* @param[in] text_style Text style.
+* @param[in] is_password EINA_TRUE if entry text should be stars.
 *
-* @return 
+* @return Pointer to created elm_entry object.
 */
 Evas_Object *utils_add_entry(Evas_Object *parent, const char *part,
                const char *text_style, Eina_Bool is_password);
 
 /**
-* @brief 
+* @brief Creates elm_radio widget.
 *
-* @param parent
-* @param part
-* @param style
-* @param text
+* @param[in] parent The radio parent.
+* @param[in] part The parent layout part name this radio should be set in. Can be NULL.
+* @param[in] style The radio style.
+* @param[in] text The radio text.
 *
-* @return 
+* @return Pointer to created elm_radio object.
 */
 Evas_Object *utils_add_radio(Evas_Object *parent, const char *part,
                const char *style, const char *text);
 
 /**
-* @brief 
+* @brief Creates elm_slider widget.
 *
-* @param parent
-* @param part
-* @param value
-* @param min_value
-* @param max_value
-* @param step
+* @param[in] parent The slider parent.
+* @param[in] part The parent layout part name this slider should be set in. Can be NULL.
+* @param[in] value Current slider value.
+* @param[in] min_value Slider min range value.
+* @param[in] max_value Slider max range value.
+* @param[in] step Slider step.
 *
-* @return 
+* @return Pointer to created elm_slider object.
 */
 Evas_Object *utils_add_slider(Evas_Object *parent, const char *part,
                int value, int min_value, int max_value, double step);
 
 /**
-* @brief 
-*
-* @param parent
-* @param part
-* @param opt_count
-* @param opt_id
-* @param opt_text
-* @param selected_opt
-* @param opt_handler
-* @param data
-*
-* @return 
+* @brief Creates elm_hoversel widget.
+*
+* @param parent The hoversel parent.
+* @param part The parent layout part name this hoversel should be set in. Can be NULL.
+* @param opt_count Hoversel dropdown selectable options.
+* @param opt_id Array of options ids.
+* @param opt_text Array of options texts.
+* @param selected_opt Index of option to be selected initially, regarding ids array.
+* @param opt_handler Callback handle when option gets selected.
+* @param data Data passed to the opt_handler.
+*
+* @return Pointer to created elm_hoversel object.
 */
 Evas_Object *utils_add_hoversel(Evas_Object *parent, const char *part,
                int opt_count, int *opt_id, const char **opt_text, int selected_opt,
                Evas_Smart_Cb opt_handler, void *data);
 
 /**
-* @brief 
-*
-* @param parent
-* @param part
-* @param field_year
-* @param field_month
-* @param field_date
-* @param field_hour
-* @param field_minute
-* @param field_ampm
-* @param time_to_set
-*
-* @return 
+* @brief Creates elm_datetime widget.
+*
+* @param parent The datetime parent.
+* @param part The parent layout part name this datetime should be set to. Can be NULL.
+* @param field_year EINA_TRUE if this field should be visible.
+* @param field_month EINA_TRUE if this field should be visible.
+* @param field_date EINA_TRUE if this field should be visible.
+* @param field_hour EINA_TRUE if this field should be visible.
+* @param field_minute EINA_TRUE if this field should be visible.
+* @param field_ampm EINA_TRUE if this field should be visible.
+* @param time_to_set Time and date to set the widget to.
+*
+* @return datetime.
 */
 Evas_Object *utils_add_datetime(Evas_Object *parent, const char *part,
                Eina_Bool field_year, Eina_Bool field_month, Eina_Bool field_date,
@@ -204,18 +204,18 @@ Evas_Object *utils_add_datetime(Evas_Object *parent, const char *part,
                struct tm *time_to_set);
 
 /**
-* @brief 
-*
-* @param parent
-* @param part
-* @param opt_count
-* @param opt_id
-* @param opt_text
-* @param selected_opt
-* @param opt_handler
-* @param data
-*
-* @return 
+* @brief  Creates elm_flipselector widget.
+*
+* @param parent The flipselector parent.
+* @param part The parent layout part name this flipselector should be set in. Can be NULL.
+* @param opt_count Flipselectorselectable options.
+* @param opt_id Array of options ids.
+* @param opt_text Array of options texts.
+* @param selected_opt Index of option to be selected initially, regarding ids array.
+* @param opt_handler Callback handle when option gets selected.
+* @param data Data passed to the opt_handler.
+*
+* @return flipselector.
 */
 Evas_Object *utils_add_flipselector(Evas_Object *parent, const char *part,
                int opt_count, int *opt_id, const char **opt_text, int selected_opt,