Merge branch 'devs/captainigloo/doc'

Improve overall documentation of Elementary. Work done on behalf of Samsung
by Openwide.

17 files changed, 494 insertions, 149 deletions

diff --git a/src/lib/elc_fileselector_legacy.h b/src/lib/elc_fileselector_legacy.h
index 2c7fcd6a5..0aa5b7949 100644
--- a/src/lib/elc_fileselector_legacy.h
+++ b/src/lib/elc_fileselector_legacy.h
@@ -408,6 +408,6 @@ EAPI Elm_Fileselector_Sort elm_fileselector_sort_method_get(const Evas_Object *o
  * @since 1.9
  * @ingroup Fileselector
  */
-EAPI void                  elm_fileselector_sort_method_set(Evas_Object *obj, Elm_Fileselector_Sort method);
+EAPI void                  elm_fileselector_sort_method_set(Evas_Object *obj, Elm_Fileselector_Sort sort);
 
 #include "elm_fileselector.eo.legacy.h"
diff --git a/src/lib/elc_naviframe_common.h b/src/lib/elc_naviframe_common.h
index 757bdb551..39d3a79e2 100644
--- a/src/lib/elc_naviframe_common.h
+++ b/src/lib/elc_naviframe_common.h
@@ -109,6 +109,7 @@ EAPI Eina_Bool        elm_naviframe_item_title_enabled_get(const Elm_Object_Item
  *
  * @param it The item to set the callback on
  * @param func the callback function.
+ * @param data The data to be passed to this @p func call.
  *
  * @warning Don't set "clicked" callback to the prev button additionally if the
  * function does an exact same logic with this @c func. When hardware back key
diff --git a/src/lib/elm_actionslider.eo b/src/lib/elm_actionslider.eo
index 27d74ea2e..84f42d76e 100644
--- a/src/lib/elm_actionslider.eo
+++ b/src/lib/elm_actionslider.eo
@@ -25,7 +25,7 @@ class Elm_Actionslider (Elm_Layout)
          set {
             /*@
             Set actionslider magnet position. To make multiple positions magnets @c or
-            them together(e.g.: #ELM_ACTIONSLIDER_LEFT | #ELM_ACTIONSLIDER_RIGHT)
+            them together (e.g. #ELM_ACTIONSLIDER_LEFT | #ELM_ACTIONSLIDER_RIGHT)
 
             @ingroup Actionslider */
          }
diff --git a/src/lib/elm_app_client.eo b/src/lib/elm_app_client.eo
index c2b4bdd1e..65661581e 100644
--- a/src/lib/elm_app_client.eo
+++ b/src/lib/elm_app_client.eo
@@ -8,7 +8,7 @@ class Elm_App_Client (Eo.Base)
             /*@ Return a iterator with all views of application. */
          }
          values {
-            iterator *ret; /*@ the iterator with all views, must be freed after use */
+            iterator *ret; /*@ The iterator with all views, must be freed after use */
          }
       }
       package {
@@ -35,7 +35,7 @@ class Elm_App_Client (Eo.Base)
          /*@ Terminate application. */
       }
       view_open {
-         /*@ Open a application view. */
+         /*@ Open an application view. */
          params {
             @in Eina_Value *args; /*@ an array of */
             @in Elm_App_Client_Open_View_Cb view_open_cb; /*@ callback to be called when view open */
diff --git a/src/lib/elm_button.eo b/src/lib/elm_button.eo
index d0651f405..5d3027f8e 100644
--- a/src/lib/elm_button.eo
+++ b/src/lib/elm_button.eo
@@ -88,7 +88,7 @@ class Elm_Button (Elm_Layout, Evas.Clickable_Interface,
       }
       admits_autorepeat {
          get {
-            /*@ No description supplied by the EAPI. */
+            /*@ Get whether the button supports autorepeat. */
             legacy: null;
          }
          values {
diff --git a/src/lib/elm_config.h b/src/lib/elm_config.h
index aa8a7cb4b..58d23df56 100644
--- a/src/lib/elm_config.h
+++ b/src/lib/elm_config.h
@@ -430,7 +430,7 @@ EAPI double       elm_config_scroll_thumbscroll_friction_standard_get(void);
  * same with thumbscroll friction, if the velocity is same with standard
  * velocity.
  *
- * @param friction the thumb scroll friction standard
+ * @param standard the thumb scroll friction standard
  *
  * @see elm_config_thumbscroll_friction_standard_get()
  * @ingroup Scrolling
@@ -524,7 +524,7 @@ EAPI double       elm_config_scroll_thumbscroll_acceleration_time_limit_get(void
 /**
  * Set the time limit for accelerating velocity.
  *
- * @param threshold the thumb scroll acceleration time limit
+ * @param time_limit the thumb scroll acceleration time limit
  *
  * @see elm_config_thumbscroll_acceleration_time_limit_get()
  * @ingroup Scrolling
@@ -543,7 +543,7 @@ EAPI double       elm_config_scroll_thumbscroll_acceleration_weight_get(void);
 /**
  * Set the weight for the acceleration.
  *
- * @param threshold the thumb scroll acceleration weight
+ * @param weight the thumb scroll acceleration weight
  *
  * @see elm_config_thumbscroll_acceleration_weight_get()
  * @ingroup Scrolling
@@ -960,7 +960,7 @@ EAPI Eina_Bool        elm_config_access_get(void);
 /**
  * Set access mode
  *
- * @param is_accesss If @c EINA_TRUE, enables access mode
+ * @param is_access If @c EINA_TRUE, enables access mode
  *
  * @note Elementary objects may have information (e.g. label on the elm_button)
  * to be read. This information is read by access module when an object
@@ -1377,13 +1377,13 @@ EAPI Eina_Bool elm_config_item_select_on_focus_disabled_get(void);
 /**
  * Set the disable status of the item select on focus feature.
  *
- * @param disable Disable item select on focus if @c EINA_TRUE, enable otherwise
+ * @param disabled Disable item select on focus if @c EINA_TRUE, enable otherwise
  *
  * @see elm_config_item_select_on_focus_disabled_get
  * @since 1.10
  * @ingroup Focus
  */
-EAPI void elm_config_item_select_on_focus_disabled_set(Eina_Bool enabled);
+EAPI void elm_config_item_select_on_focus_disabled_set(Eina_Bool disabled);
 
 /**
  * Get status of first item focus on first focusin feature.
@@ -1399,7 +1399,7 @@ EAPI Eina_Bool elm_config_first_item_focus_on_first_focusin_get(void);
 /**
  * Set the first item focus on first focusin feature.
  *
- * @param enable first_item_focus_on_first_focusin if @c EINA_TRUE, enable otherwise
+ * @param enabled first_item_focus_on_first_focusin if @c EINA_TRUE, enable otherwise
  *
  * @see elm_config_first_item_focus_on_first_focusin_get
  * @since 1.11
@@ -1483,7 +1483,7 @@ EAPI double   elm_config_glayer_double_tap_timeout_get(void);
 /**
  * Set the duration for occurring double tap event of gesture layer.
  *
- * @param long_tap_timeout Timeout for double tap event of gesture layer.
+ * @param double_tap_timeout Timeout for double tap event of gesture layer.
  * @ingroup Elm_Gesture_Layer
  * @since 1.8
  */
diff --git a/src/lib/elm_container.eo b/src/lib/elm_container.eo
index b306f7ed2..899068c59 100644
--- a/src/lib/elm_container.eo
+++ b/src/lib/elm_container.eo
@@ -6,7 +6,7 @@ class Elm_Container (Elm_Widget)
    properties {
       content_swallow_list {
          get {
-            /*@ No description supplied by the EAPI. */
+            /*@ Get the list of swallow parts in the object. */
          }
          values {
             list *ret; /*@ list */
@@ -15,22 +15,22 @@ class Elm_Container (Elm_Widget)
    }
    methods {
       content_set {
-         /*@ No description supplied by the EAPI. */
+         /*@ Swallow the given object into the given part of the container. */
          params {
-            @in const(char)* name;
-            @in Evas_Object *content;
+            @in const(char)* name; /*@ the part in which to swallow the object */
+            @in Evas_Object *content; /*@ the object to swallow */
          }
          return: bool;
       }
       content_get {
-         /*@ No description supplied by the EAPI. */
+         /*@ Get the object swallowed in the given part of the container. */
          params {
-            @in const(char)* name;
+            @in const(char)* name; /*@ the part in which the object is swallowed */
          }
          return: Evas_Object *;
       }
       content_unset {
-         /*@ No description supplied by the EAPI. */
+         /*@ Unswallow the object in the given part of the container and return it. */
          params {
             @in const(char)* name;
          }
diff --git a/src/lib/elm_general.h b/src/lib/elm_general.h
index 88d9ff16f..a800f242a 100644
--- a/src/lib/elm_general.h
+++ b/src/lib/elm_general.h
@@ -134,20 +134,28 @@ typedef enum
    ELM_POLICY_THROTTLE_NEVER /**< never throttle when windows are all hidden, regardless of config settings */
 } Elm_Policy_Throttle;
 
+/**
+ * Possible values for the #ELM_OBJECT_SELECT_MODE policy.
+ * @since 1.7
+ */
 typedef enum
 {
    ELM_OBJECT_SELECT_MODE_DEFAULT = 0, /**< default select mode. Once an item is selected, it would stay highlighted and not going to call selected callback again even it was clicked. Items can get focus. */
    ELM_OBJECT_SELECT_MODE_ALWAYS, /**< always select mode. Item selected callbacks will be called every time for click events, even after the item was already selected. Items can get focus. */
    ELM_OBJECT_SELECT_MODE_NONE, /**< no select mode. Items will never be highlighted and selected but the size will be adjusted by the finger size configuration. Items can't get focus. */
    ELM_OBJECT_SELECT_MODE_DISPLAY_ONLY, /**< no select mode with no finger size rule. Items will never be highlighted and selected and ignore the finger size. So the item size can be reduced below than the finger size configuration. Items can't get focus. */
-   ELM_OBJECT_SELECT_MODE_MAX
+   ELM_OBJECT_SELECT_MODE_MAX /**< canary value: any value greater or equal to ELM_OBJECT_SELECT_MODE_MAX is forbidden. */
 } Elm_Object_Select_Mode;
 
+/**
+ * Possible values for the #ELM_OBJECT_MULTI_SELECT_MODE policy.
+ * @since 1.8
+ */
 typedef enum
 {
    ELM_OBJECT_MULTI_SELECT_MODE_DEFAULT = 0, /**< default multiple select mode */
    ELM_OBJECT_MULTI_SELECT_MODE_WITH_CONTROL, /**< disallow mutiple selection when clicked without control key pressed */
-   ELM_OBJECT_MULTI_SELECT_MODE_MAX
+   ELM_OBJECT_MULTI_SELECT_MODE_MAX /**< canary value: any value greater or equal to ELM_OBJECT_MULTI_SELECT_MODE_MAX is forbidden. */
 } Elm_Object_Multi_Select_Mode;
 
 typedef Eina_Bool             (*Elm_Event_Cb)(void *data, Evas_Object *obj, Evas_Object *src, Evas_Callback_Type type, void *event_info); /**< Function prototype definition for callbacks on input events happening on Elementary widgets. @a data will receive the user data pointer passed to elm_object_event_callback_add(). @a src will be a pointer to the widget on which the input event took place. @a type will get the type of this event and @a event_info, the struct with details on this event. */
diff --git a/src/lib/elm_gesture_layer_common.h b/src/lib/elm_gesture_layer_common.h
index 398ce1862..60f52605c 100644
--- a/src/lib/elm_gesture_layer_common.h
+++ b/src/lib/elm_gesture_layer_common.h
@@ -434,7 +434,7 @@ EAPI double elm_gesture_layer_double_tap_timeout_get(const Evas_Object *obj);
  * Set to ZERO if you want GLayer to use system finger size value (default)
  *
  * @param obj gesture-layer.
- * @param fsize Finger size
+ * @param sz Finger size
  *
  * @since 1.8
  * @ingroup Elm_Gesture_Layer
diff --git a/src/lib/elm_image.eo b/src/lib/elm_image.eo
index 0f14c1940..dc77b55af 100644
--- a/src/lib/elm_image.eo
+++ b/src/lib/elm_image.eo
@@ -30,15 +30,25 @@ class Elm_Image (Elm_Widget, Efl.File, Efl.Image, Evas.Clickable_Interface,
       }
       resize_down {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@
+              Set whether the object's image can be resized to a size smaller than the original one.
+
+              @ingroup Image
+              @since 1.7
+             */
             legacy: null;
          }
          get {
-            /*@ No description supplied by the EAPI. */
+            /*@
+              Get whether the object's image can be resized to a size smaller than the original one.
+
+              @ingroup Image
+              @since 1.7
+             */
             legacy: null;
          }
          values {
-            bool resize_down;
+            bool resize_down; /*@ whether resizing down is allowed */
          }
       }
       animated_play {
@@ -87,15 +97,25 @@ class Elm_Image (Elm_Widget, Efl.File, Efl.Image, Evas.Clickable_Interface,
       }
       resize_up {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@
+              Set whether the object's image can be resized to a size larget than the original one.
+
+              @ingroup Image
+              @since 1.7
+             */
             legacy: null;
          }
          get {
-            /*@ No description supplied by the EAPI. */
+            /*@
+              Get whether the object's image can be resized to a size larget than the original one.
+
+              @ingroup Image
+              @since 1.7
+             */
             legacy: null;
          }
          values {
-            bool resize_up;
+            bool resize_up; /*@ whether resizing up is allowed */
          }
       }
       smooth {
@@ -198,28 +218,62 @@ class Elm_Image (Elm_Widget, Efl.File, Efl.Image, Evas.Clickable_Interface,
       }
       scale {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@
+              Set the scale of the object's image.
+
+              @ingroup Image
+              @since 1.7
+             */
             legacy: null;
          }
          get {
-            /*@ No description supplied by the EAPI. */
+            /*@
+              Get the scale of the object's image.
+
+              @ingroup Image
+              @since 1.7
+             */
             legacy: null;
          }
          values {
-            double scale;
+            double scale; /*@ Object's image scale. */
          }
       }
       fill_inside {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@
+              Set the resize method for the object's internal image when maintaining a given aspect ratio.
+
+              If @p fill_inside is true, image does not overflow the widget and
+              blank spaces are added to fill the space that is still free. If it
+              is false, the image overflows the image will fill all space and
+              overflow in its larger dimension.
+
+              You can think of it as "fill: inside" or "fill: outside" and not as
+              "fill the inside".
+
+              @see elm_image_fill_inside_get()
+              @see elm_image_fill_outside_get()
+              @see elm_image_fill_outside_set()
+              @ingroup Image
+              @since 1.7
+             */
             legacy: null;
          }
          get {
-            /*@ No description supplied by the EAPI. */
+            /*@
+              Set the resize method for the object's internal image when maintaining a given aspect ratio.
+
+              @see elm_image_fill_inside_set()
+              @see elm_image_fill_outside_get()
+              @see elm_image_fill_outside_set()
+              @ingroup Image
+              @since 1.7
+             */
             legacy: null;
          }
          values {
-            bool fill_inside;
+            bool fill_inside; /*@ Resize method for the object's internal image. */
          }
       }
       aspect_fixed {
@@ -293,6 +347,8 @@ class Elm_Image (Elm_Widget, Efl.File, Efl.Image, Evas.Clickable_Interface,
             @note This option will have no effect if
             elm_image_aspect_fixed_set() is set to @c EINA_FALSE.
 
+            @see elm_image_fill_inside_get()
+            @see elm_image_fill_inside_set()
             @see elm_image_fill_outside_get()
             @see elm_image_aspect_fixed_set()
 
@@ -304,6 +360,8 @@ class Elm_Image (Elm_Widget, Efl.File, Efl.Image, Evas.Clickable_Interface,
 
             @return @c EINA_TRUE if the object is filled outside, @c EINA_FALSE otherwise.
 
+            @see elm_image_fill_inside_get()
+            @see elm_image_fill_inside_set()
             @see elm_image_fill_outside_set()
 
             @ingroup Image */
@@ -466,7 +524,11 @@ class Elm_Image (Elm_Widget, Efl.File, Efl.Image, Evas.Clickable_Interface,
    }
    methods {
       sizing_eval {
-         /*@ No description supplied by the EAPI. */
+         /*@
+           Re-evaluate the object's final geometry.
+
+           @ingroup Image
+           @since 1.7 */
          legacy: null;
       }
    }
diff --git a/src/lib/elm_interface_scrollable.eo b/src/lib/elm_interface_scrollable.eo
index 16d398146..320651cee 100644
--- a/src/lib/elm_interface_scrollable.eo
+++ b/src/lib/elm_interface_scrollable.eo
@@ -2,30 +2,67 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
 {
    legacy_prefix: null;
    eo_prefix: elm_interface_scrollable;
-   data: Elm_Scrollable_Smart_Interface_Data; 
+   data: Elm_Scrollable_Smart_Interface_Data;
    properties {
       gravity {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set scrolling gravity on the scrollable
+
+             The gravity defines how the scroller will adjust its view
+             when the size of the scroller contents increases.
+
+             The scroller will adjust the view to glue itself as follows.
+
+              x=0.0, for staying where it is relative to the left edge of the content
+              x=1.0, for staying where it is relative to the rigth edge of the content
+              y=0.0, for staying where it is relative to the top edge of the content
+              y=1.0, for staying where it is relative to the bottom edge of the content
+
+             Default values for x and y are 0.0
+
+             @ingroup Widget
+             */
          }
          get {
-            /*@ No description supplied by the EAPI. */
+            /*@ Get scrolling gravity on the scrollable
+
+             The gravity defines how the scroller will adjust its view
+             when the size of the scroller contents increases.
+
+             The scroller will adjust the view to glue itself as follows.
+
+              x=0.0, for staying where it is relative to the left edge of the content
+              x=1.0, for staying where it is relative to the rigth edge of the content
+              y=0.0, for staying where it is relative to the top edge of the content
+              y=1.0, for staying where it is relative to the bottom edge of the content
+
+             Default values for x and y are 0.0
+
+             @ingroup Widget
+             */
          }
          values {
-            double x;
-            double y;
+            double x; /*@ Horizontal scrolling gravity */
+            double y; /*@ Vertical scrolling gravity */
          }
       }
       bounce_allow {
+         /* @brief Bouncing behavior
+          *
+          * When scrolling, the scroller may "bounce" when reaching an edge of the
+          * content object. This is a visual way to indicate the end has been reached.
+          * This is enabled by default for both axis. This API will set if it is enabled
+          * for the given axis with the boolean parameters for each axis.
+          *
+          * @ingroup Widget
+          */
          set {
-            /*@ No description supplied by the EAPI. */
          }
          get {
-            /*@ No description supplied by the EAPI. */
          }
          values {
-            bool horiz;
-            bool vert;
+            bool horiz; /*@ Horizontal bounce policy. */
+            bool vert; /*@ Vertical bounce policy. */
          }
       }
       wheel_disabled {
@@ -40,14 +77,30 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
          }
       }
       movement_block {
+         /*@
+          * @brief Blocking of scrolling (per axis)
+          *
+          * This function will block scrolling movement (by input of a user) in
+          * a given direction. One can disable movements in the X axis, the Y
+          * axis or both. The default value is #ELM_SCROLLER_MOVEMENT_NO_BLOCK,
+          * where movements are allowed in both directions.
+          *
+          * What makes this function different from
+          * freeze_push(), hold_push() and lock_x_set() (or lock_y_set())
+          * is that it @b doesn't propagate its effects to any parent or child
+          * widget of @a obj. Only the target scrollable widget will be locked
+          * with regard to scrolling.
+          *
+          * @since 1.8
+          *
+          * @ingroup Widget
+          */
          set {
-            /*@ No description supplied by the EAPI. */
          }
          get {
-            /*@ No description supplied by the EAPI. */
          }
          values {
-            Elm_Scroller_Movement_Block block;
+            Elm_Scroller_Movement_Block block; /*@ Which axis (or axes) to block */
          }
       }
       momentum_animator_disabled {
@@ -62,29 +115,48 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
          }
       }
       policy {
+         /*@
+          * @brief Scrollbar visibility policy
+          *
+          * #ELM_SCROLLER_POLICY_AUTO means the scrollbar is made visible if it is
+          * needed, and otherwise kept hidden. #ELM_SCROLLER_POLICY_ON turns it on all
+          * the time, and #ELM_SCROLLER_POLICY_OFF always keeps it off. This applies
+          * respectively for the horizontal and vertical scrollbars.
+          *
+          * @ingroup Widget
+          */
          set {
-            /*@ No description supplied by the EAPI. */
          }
          get {
-            /*@ No description supplied by the EAPI. */
          }
          values {
-            Elm_Scroller_Policy hbar;
-            Elm_Scroller_Policy vbar;
+            Elm_Scroller_Policy hbar; /*@ Horizontal scrollbar policy */
+            Elm_Scroller_Policy vbar; /*@ Vertical scrollbar policy */
          }
       }
       content_region {
+         /*@
+          * @brief Currently visible content region
+          *
+          * This gets the current region in the content object that is visible through
+          * the scroller. The region co-ordinates are returned in the @p x, @p y, @p
+          * w, @p h values pointed to.
+          *
+          * @note All coordinates are relative to the content.
+          *
+          * @see elm_scroller_region_show()
+          *
+          * @ingroup Widget
+          */
          set {
-            /*@ No description supplied by the EAPI. */
          }
          get {
-            /*@ No description supplied by the EAPI. */
          }
          values {
-            Evas_Coord x;
-            Evas_Coord y;
-            Evas_Coord w;
-            Evas_Coord h;
+            Evas_Coord x; /*@ X coordinate of the region */
+            Evas_Coord y; /*@ Y coordinate of the region */
+            Evas_Coord w; /*@ Width of the region */
+            Evas_Coord h; /*@ Height of the region */
          }
       }
       repeat_events {
@@ -99,15 +171,29 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
          }
       }
       page_size {
+         /*@
+          * @brief Scroll page size relative to viewport size.
+          *
+          * The scroller is capable of limiting scrolling by the user to "pages". That
+          * is to jump by and only show a "whole page" at a time as if the continuous
+          * area of the scroller content is split into page sized pieces. This sets
+          * the size of a page relative to the viewport of the scroller. 1.0 is "1
+          * viewport" is size (horizontally or vertically). 0.0 turns it off in that
+          * axis. This is mutually exclusive with page size
+          * (see elm_scroller_page_size_set()  for more information). Likewise 0.5
+          * is "half a viewport". Sane usable values are normally between 0.0 and 1.0
+          * including 1.0. If you only want 1 axis to be page "limited", use 0.0 for
+          * the other axis.
+          *
+          * @ingroup Widget
+          */
          set {
-            /*@ No description supplied by the EAPI. */
          }
          get {
-            /*@ No description supplied by the EAPI. */
          }
          values {
-            Evas_Coord x;
-            Evas_Coord y;
+            Evas_Coord x; /*@ The horizontal page relative size */
+            Evas_Coord y; /*@ The vertical page relative size */
          }
       }
       bounce_animator_disabled {
@@ -134,15 +220,30 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
          }
       }
       page_snap_allow {
+         /*@
+          * @brief Page snapping behavior
+          *
+          * When scrolling, if a scroller is paged (see
+          * elm_scroller_page_size_set() and elm_scroller_page_relative_set()),
+          * the scroller may snap to pages when being scrolled, i.e., even if
+          * it had momentum to scroll further, it will stop at the next page
+          * boundaries. This is @b disabled, by default, for both axis. This
+          * function will set if it that is enabled or not, for each axis.
+          *
+          * @note If @a obj is not set to have pages, nothing will happen after
+          * this call.
+          *
+          * @since 1.8
+          *
+          * @ingroup Widget
+          */
          set {
-            /*@ Enable/disable page bouncing, for paged scrollers, on each axis. */
          }
          get {
-            /*@ Get wether page bouncing is enabled, for paged scrollers, on each axis. */
          }
          values {
-            bool horiz;
-            bool vert;
+            bool horiz; /*@ Allow snap horizontally */
+            bool vert;  /*@ Allow snap vertically */
          }
       }
       paging {
@@ -160,14 +261,28 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
          }
       }
       single_direction {
+         /*@
+          * @brief Single direction scroll configuration
+          *
+          * This makes it possible to restrict scrolling to a single direction,
+          * with a "soft" or "hard" behavior.
+          *
+          * The hard behavior restricts the scrolling to a single direction all
+          * of the time while the soft one will restrict depending on factors
+          * such as the movement angle. If the user scrolls roughly in one
+          * direction only, it will only move according to it while if the move
+          * was clearly wanted on both axes, it will happen on both of them.
+          *
+          * @since 1.8
+          *
+          * @ingroup Widget
+          */
          set {
-            /*@ No description supplied by the EAPI. */
          }
          get {
-            /*@ No description supplied by the EAPI. */
          }
          values {
-            Elm_Scroller_Single_Direction single_dir;
+            Elm_Scroller_Single_Direction single_dir; /*@ The single direction scroll policy */
          }
       }
       step_size {
@@ -184,26 +299,38 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
       }
       scroll_up_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the content has been moved up.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb scroll_up_cb;
+            Elm_Interface_Scrollable_Cb scroll_up_cb; /*@ The callback */
          }
       }
       hbar_drag_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the horizontal scrollbar is dragged.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb hbar_drag_cb;
+            Elm_Interface_Scrollable_Cb hbar_drag_cb; /*@ The callback */
          }
       }
       drag_start_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when dragging of the contents has started.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb drag_start_cb;
+            Elm_Interface_Scrollable_Cb drag_start_cb; /*@ The callback */
          }
       }
       freeze {
@@ -224,42 +351,63 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
       }
       scroll_left_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the content has been moved to the left
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb scroll_left_cb;
+            Elm_Interface_Scrollable_Cb scroll_left_cb; /*@ The callback */
          }
       }
       vbar_press_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the vertical scrollbar is pressed.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb vbar_press_cb;
+            Elm_Interface_Scrollable_Cb vbar_press_cb; /*@ The callback */
          }
       }
       hbar_press_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the horizontal scrollbar is pressed.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb hbar_press_cb;
+            Elm_Interface_Scrollable_Cb hbar_press_cb; /*@ The callback */
          }
       }
       hbar_unpress_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the horizontal scrollbar is unpressed.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb hbar_unpress_cb;
+            Elm_Interface_Scrollable_Cb hbar_unpress_cb; /*@ The callback */
          }
       }
       drag_stop_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when dragging of the contents has stopped.
+             *
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb drag_stop_cb;
+            Elm_Interface_Scrollable_Cb drag_stop_cb; /*@ The callback */
          }
       }
       extern_pan {
@@ -272,10 +420,14 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
       }
       page_change_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the visible page changes.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb page_change_cb;
+            Elm_Interface_Scrollable_Cb page_change_cb; /*@ The callback */
          }
       }
       hold {
@@ -288,18 +440,26 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
       }
       animate_start_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the scrolling animation has started.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb animate_start_cb;
+            Elm_Interface_Scrollable_Cb animate_start_cb; /*@ The callback */
          }
       }
       scroll_down_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the content has been moved down.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb scroll_down_cb;
+            Elm_Interface_Scrollable_Cb scroll_down_cb; /*@ The callback */
          }
       }
       page_relative {
@@ -313,18 +473,26 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
       }
       scroll_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the content has been moved.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb scroll_cb;
+            Elm_Interface_Scrollable_Cb scroll_cb; /*@ The callback */
          }
       }
       animate_stop_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the scrolling animation has stopped.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb animate_stop_cb;
+            Elm_Interface_Scrollable_Cb animate_stop_cb; /*@ The callback */
          }
       }
       mirrored {
@@ -345,10 +513,14 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
       }
       scroll_right_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the content has been moved to the right.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb scroll_right_cb;
+            Elm_Interface_Scrollable_Cb scroll_right_cb; /*@ The callback */
          }
       }
       content {
@@ -361,50 +533,74 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
       }
       edge_left_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the left edge of the content has been reached.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb edge_left_cb;
+            Elm_Interface_Scrollable_Cb edge_left_cb; /*@ The callback */
          }
       }
       vbar_drag_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the horizontal scrollbar is dragged.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb vbar_drag_cb;
+            Elm_Interface_Scrollable_Cb vbar_drag_cb; /*@ The callback */
          }
       }
       vbar_unpress_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the horizontal scrollbar is unpressed.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb vbar_unpress_cb;
+            Elm_Interface_Scrollable_Cb vbar_unpress_cb; /*@ The callback */
          }
       }
       edge_bottom_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the bottom edge of the content has been reached.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb edge_bottom_cb;
+            Elm_Interface_Scrollable_Cb edge_bottom_cb; /*@ The callback */
          }
       }
       edge_right_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the right edge of the content has been reached.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb edge_right_cb;
+            Elm_Interface_Scrollable_Cb edge_right_cb; /*@ The callback */
          }
       }
       edge_top_cb {
          set {
-            /*@ No description supplied by the EAPI. */
+            /*@ Set the callback to run when the top edge of the content has been reached.
+
+             @ingroup Widget
+
+             */
          }
          values {
-            Elm_Interface_Scrollable_Cb edge_top_cb;
+            Elm_Interface_Scrollable_Cb edge_top_cb; /*@ The callback */
          }
       }
       objects {
@@ -418,20 +614,42 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
       }
       last_page {
          get {
-            /*@ No description supplied by the EAPI. */
+            /*@ Get scroll last page number.
+
+             The page number starts from 0. 0 is the first page.
+             This returns the last page number among the pages.
+
+             @see elm_scroller_current_page_get()
+             @see elm_scroller_page_show()
+             @see elm_scroller_page_bring_in()
+
+             @ingroup Widget
+             */
          }
          values {
-            int pagenumber_h;
-            int pagenumber_v;
+            int pagenumber_h; /*@ The horizontal page number */
+            int pagenumber_v; /*@ The vertical page number */
          }
       }
       current_page {
          get {
-            /*@ No description supplied by the EAPI. */
+            /*@ Get scroll current page number.
+
+             The page number starts from 0. 0 is the first page.
+             Current page means the page which meets the top-left of the viewport.
+             If there are two or more pages in the viewport, it returns the number of the page
+             which meets the top-left of the viewport.
+
+             @see elm_scroller_last_page_get()
+             @see elm_scroller_page_show()
+             @see elm_scroller_page_bring_in()
+
+             @ingroup Widget
+             */
          }
          values {
-            int pagenumber_h;
-            int pagenumber_v;
+            int pagenumber_h; /*@ The horizontal page number */
+            int pagenumber_v; /*@ The vertical page number */
          }
       }
       content_viewport_geometry {
@@ -447,11 +665,17 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
       }
       content_size {
          get {
-            /*@ No description supplied by the EAPI. */
+            /*@ Get the size of the content object
+
+             This gets the size of the content object of the scroller.
+
+             @ingroup Scroller
+             */
          }
          values {
-            Evas_Coord w;
-            Evas_Coord h;
+            Evas_Coord w; /*@ Width of the content object. */
+            Evas_Coord h; /*@ Height of the content object. */
+
          }
       }
    }
@@ -472,42 +696,86 @@ mixin Elm_Interface_Scrollable(Evas.Scrollable_Interface, Evas.Object_Smart)
          }
       }
       page_show {
-         /*@ No description supplied by the EAPI. */
+         /*@ Show a specific virtual region within the scroller content object by page number.
+
+          0, 0 of the indicated page is located at the top-left of the viewport.
+          This will jump to the page directly without animation.
+
+          @see elm_scroller_page_bring_in()
+
+          @ingroup Widget
+          */
          params {
-            @in int pagenumber_h;
-            @in int pagenumber_v;
+            @in int pagenumber_h; /*@ The horizontal page number */
+            @in int pagenumber_v; /*@ The vertical page number */
          }
       }
       region_bring_in {
-         /*@ No description supplied by the EAPI. */
+         /*@ Show a specific virtual region within the scroller content object.
+
+          This will ensure all (or part if it does not fit) of the designated
+          region in the virtual content object (0, 0 starting at the top-left of the
+          virtual content object) is shown within the scroller. Unlike
+          elm_scroller_region_show(), this allows the scroller to "smoothly slide"
+          to this location (if configuration in general calls for transitions). It
+          may not jump immediately to the new location and make take a while and
+          show other content along the way.
+
+          @see elm_scroller_region_show()
+
+          @ingroup Widget
+          */
          params {
-            @in Evas_Coord x;
-            @in Evas_Coord y;
-            @in Evas_Coord w;
-            @in Evas_Coord h;
+            @in Evas_Coord x; /*@ X coordinate of the region */
+            @in Evas_Coord y; /*@ Y coordinate of the region */
+            @in Evas_Coord w; /*@ Width of the region */
+            @in Evas_Coord h; /*@ Height of the region */
          }
       }
       page_bring_in {
-         /*@ No description supplied by the EAPI. */
+         /*@ Show a specific virtual region within the scroller content object by page number.
+
+          0, 0 of the indicated page is located at the top-left of the viewport.
+          This will slide to the page with animation.
+
+          @see elm_scroller_page_show()
+
+          @ingroup Scroller
+          */
          params {
-            @in int pagenumber_h;
-            @in int pagenumber_v;
+            @in int pagenumber_h; /*@ The horizontal page number */
+            @in int pagenumber_v; /*@ The vertical page number */
          }
       }
       content_region_show {
-         /*@ No description supplied by the EAPI. */
+         /*@ Show a specific virtual region within the scroller content object
+
+          This will ensure all (or part if it does not fit) of the designated
+          region in the virtual content object (0, 0 starting at the top-left of the
+          virtual content object) is shown within the scroller.
+
+          @ingroup Widget
+          */
          params {
-            @in Evas_Coord x;
-            @in Evas_Coord y;
-            @in Evas_Coord w;
-            @in Evas_Coord h;
+            @in Evas_Coord x; /*@ X coordinate of the region */
+            @in Evas_Coord y; /*@ Y coordinate of the region */
+            @in Evas_Coord w; /*@ Width of the region */
+            @in Evas_Coord h; /*@ Height of the region */
          }
       }
       content_min_limit {
-         /*@ No description supplied by the EAPI. */
+         /*@ Prevent the scrollable from being smaller than the minimum size of the content.
+
+          By default the scroller will be as small as its design allows,
+          irrespective of its content. This will make the scroller minimum size the
+          right size horizontally and/or vertically to perfectly fit its content in
+          that direction.
+
+          @ingroup Widget
+          */
          params {
-            @in bool w;
-            @in bool h;
+            @in bool w; /*@ whether to limit the minimum horizontal size */
+            @in bool h; /*@ whether to limit the minimum vertical size */
          }
       }
    }
diff --git a/src/lib/elm_map_common.h b/src/lib/elm_map_common.h
index 74cec96da..9d30a7155 100644
--- a/src/lib/elm_map_common.h
+++ b/src/lib/elm_map_common.h
@@ -509,10 +509,10 @@ EAPI void                  elm_map_overlays_show(Eina_List *overlays);
 EAPI void                  elm_map_overlay_get_cb_set(Elm_Map_Overlay *overlay, Elm_Map_Overlay_Get_Cb get_cb, void *data);
 
 /**
- * Set the get callback function to call when the overlay is deleted.
+ * Set the del callback function to call when the overlay is deleted.
  *
  * @param overlay The overlay to own the del callback function.
- * @param get_cb The callback function.
+ * @param del_cb The callback function.
  * @param data The user callback data.
  *
  * If the overlay is deleted, the callback wll be called.
diff --git a/src/lib/elm_prefs_data.h b/src/lib/elm_prefs_data.h
index 603cbcb00..e2890c6f7 100644
--- a/src/lib/elm_prefs_data.h
+++ b/src/lib/elm_prefs_data.h
@@ -181,7 +181,7 @@ EAPI void            elm_prefs_data_unref(Elm_Prefs_Data *prefs_data);
  * Set (or delete) one value of a given prefs data handle.
  *
  * @param prefs_data A valid prefs data handle
- * @param name The (unique) name (key) of the given value
+ * @param path The (unique) name (key) of the given value
  * @param type The item type to which the value is to be associated
  * @param value The value, itself. It must be a valid @c Eina_Value
  *              handle, bound to a given type and value or @c NULL. On
@@ -204,7 +204,7 @@ EAPI Eina_Bool       elm_prefs_data_value_set(Elm_Prefs_Data *prefs_data,
  * Retrieve one value of a given prefs data handle (by key).
  *
  * @param prefs_data A valid prefs data handle
- * @param name The (unique) name (key) of the given value
+ * @param path The (unique) name (key) of the given value
  * @param type The item type associated with the value
  * @param value A valid @c Eina_Value handle, where to store the
  *              value, itself.
@@ -258,7 +258,7 @@ EAPI Eina_Bool       elm_prefs_data_event_callback_add(Elm_Prefs_Data *prefs_dat
  * @since 1.8
  */
 EAPI Eina_Bool       elm_prefs_data_event_callback_del(Elm_Prefs_Data *prefs_data,
-                                                       Elm_Prefs_Data_Event_Type t,
+                                                       Elm_Prefs_Data_Event_Type type,
                                                        Elm_Prefs_Data_Event_Cb cb,
                                                        const void *cb_data);
 
diff --git a/src/lib/elm_store.h b/src/lib/elm_store.h
index 3db9ece2f..27053287a 100644
--- a/src/lib/elm_store.h
+++ b/src/lib/elm_store.h
@@ -70,6 +70,10 @@ typedef void                                 (*Elm_Store_Item_Fetch_Cb)(void *da
 typedef void                                 (*Elm_Store_Item_Unfetch_Cb)(void *data, Elm_Store_Item *sti); /**< Function to cal lto un-fetch (free) an item */
 typedef void                                *(*Elm_Store_Item_Mapping_Cb)(void *data, Elm_Store_Item *sti, const char *part); /**< Custom mapping function to call */
 
+/**
+ * Possible mappings types.
+ * @since 1.7
+ */
 typedef enum
 {
    ELM_STORE_ITEM_MAPPING_NONE = 0,
@@ -78,7 +82,7 @@ typedef enum
    ELM_STORE_ITEM_MAPPING_ICON, /**< char * -> icon path */
    ELM_STORE_ITEM_MAPPING_PHOTO, /**< char * -> photo path */
    ELM_STORE_ITEM_MAPPING_CUSTOM, /**< item->custom(it->data, it, part) -> void * (-> any) */
-   ELM_STORE_ITEM_MAPPING_LAST
+   ELM_STORE_ITEM_MAPPING_LAST, /** canary value: any value greater or equal to ELM_STORE_ITEM_MAPPING_LAST is forbidden. */
 } Elm_Store_Item_Mapping_Type;
 
 struct _Elm_Store_Item_Mapping_Icon
diff --git a/src/lib/elm_toolbar_common.h b/src/lib/elm_toolbar_common.h
index 032f6f469..09d1eabd5 100644
--- a/src/lib/elm_toolbar_common.h
+++ b/src/lib/elm_toolbar_common.h
@@ -420,23 +420,25 @@ EAPI Elm_Toolbar_Item_State      *elm_toolbar_item_state_prev(Elm_Object_Item *i
  * Show a specific item, when the toolbar can be scrolled.
  *
  * @param it the toolbar item
+ * @param scrollto the position the item should appear at
  *
  * see elm_toolbar_item_bring_in()
  *
  * @since 1.8
  * @ingroup Toolbar
  */
-EAPI void                          elm_toolbar_item_show(Elm_Object_Item *it, Elm_Toolbar_Item_Scrollto_Type type);
+EAPI void                          elm_toolbar_item_show(Elm_Object_Item *it, Elm_Toolbar_Item_Scrollto_Type scrollto);
 
 /**
  * Show a specific item with scroll animation, when the toolbar can be scrolled.
  *
  * @param it the toolbar item
+ * @param scrollto the position the item should appear at
  *
  * see elm_toolbar_item_show()
  *
  * @since 1.8
  * @ingroup Toolbar
  */
-EAPI void                          elm_toolbar_item_bring_in(Elm_Object_Item *it, Elm_Toolbar_Item_Scrollto_Type type);
+EAPI void                          elm_toolbar_item_bring_in(Elm_Object_Item *it, Elm_Toolbar_Item_Scrollto_Type scrollto);
 
diff --git a/src/lib/elm_transit.h b/src/lib/elm_transit.h
index b490bff7a..32ffe5982 100644
--- a/src/lib/elm_transit.h
+++ b/src/lib/elm_transit.h
@@ -633,7 +633,7 @@ EAPI Eina_List             *elm_transit_chain_transits_get(const Elm_Transit *tr
 /**
  * Set the smooth effect for a transit.
  *
- * @param obj The transit object
+ * @param transit The transit object
  * @param enabled enable or disable smooth map rendering
  *
  * This sets smoothing for transit map rendering. If the object added in a
@@ -646,14 +646,14 @@ EAPI Eina_List             *elm_transit_chain_transits_get(const Elm_Transit *tr
  *
  * @ingroup Transit
  */
-EAPI void                   elm_transit_smooth_set(Elm_Transit *transit, Eina_Bool smooth);
+EAPI void                   elm_transit_smooth_set(Elm_Transit *transit, Eina_Bool enabled);
 
 /**
  * Get the smooth scaling for transit map rendering
  *
  * This gets smooth scaling for transit map rendering.
  *
- * @param obj The transit object
+ * @param transit The transit object
  * @return @c EINA_TRUE if the smooth is enabled, @c EINA_FALSE otherwise.
  *
  * @see elm_transit_smooth_set()
diff --git a/src/lib/elm_win.eo b/src/lib/elm_win.eo
index dc51063e2..ff71cd16c 100644
--- a/src/lib/elm_win.eo
+++ b/src/lib/elm_win.eo
@@ -134,7 +134,7 @@ class Elm_Win (Elm_Widget, Elm_Interface_Atspi_Window,
          }
          values {
             int *rotations @const_set; /*@ The array of rotation value. */
-            uint count; /*@ The number of array of rotations */
+            uint count; /*@ The size of the @param rotations array. */
          }
       }
       quickpanel_zone {