efl_ui_pager: enhance documentation and comment

7 files changed, 121 insertions, 13 deletions

diff --git a/src/lib/elementary/efl_page_indicator.eo b/src/lib/elementary/efl_page_indicator.eo
index ae3774f5d5..e4f206ae74 100644
--- a/src/lib/elementary/efl_page_indicator.eo
+++ b/src/lib/elementary/efl_page_indicator.eo
@@ -1,6 +1,11 @@
 class Efl.Page.Indicator (Efl.Object)
 {
-   [[Efl ui pager indicator class]]
+   [[Page indicator
+
+     Page indicator is used with @Efl.Ui.Pager.
+     It is located on the top layer of pager widget and helps users to know
+     the number of pages and the current page's index without scrolling.
+   ]]
    implements {
       Efl.Object.constructor;
    }
diff --git a/src/lib/elementary/efl_page_indicator_icon.eo b/src/lib/elementary/efl_page_indicator_icon.eo
index 4b74d2832f..d45e3e8606 100644
--- a/src/lib/elementary/efl_page_indicator_icon.eo
+++ b/src/lib/elementary/efl_page_indicator_icon.eo
@@ -1,6 +1,11 @@
 class Efl.Page.Indicator.Icon (Efl.Page.Indicator)
 {
-   [[Efl ui pager indicator icon class]]
+   [[Icon type page indicator
+
+     This class offers icon type indicator for @Efl.Ui.Pager.
+     This type of page indicator creates the same number of icons as pages and
+     arrange them in a linear order. An icon has two states: default and selected.
+   ]]
    implements {
       Efl.Object.constructor;
       Efl.Object.destructor;
diff --git a/src/lib/elementary/efl_page_transition.eo b/src/lib/elementary/efl_page_transition.eo
index 47cfb4fc04..77e359ce04 100644
--- a/src/lib/elementary/efl_page_transition.eo
+++ b/src/lib/elementary/efl_page_transition.eo
@@ -1,6 +1,10 @@
 class Efl.Page.Transition (Efl.Object)
 {
-   [[Efl ui pagescroller transition effect class]]
+   [[Page transition for @Efl.Ui.Pager
+
+     A page transition is essential to @Efl.Ui.Pager object and invoked whenever
+     pages are rearranged or scrolled (see @Efl.Ui.Pager).
+   ]]
    methods {
       bind {
          [[set object]]
diff --git a/src/lib/elementary/efl_page_transition_scroll.c b/src/lib/elementary/efl_page_transition_scroll.c
index 01232ebaab..f3d7526dbc 100644
--- a/src/lib/elementary/efl_page_transition_scroll.c
+++ b/src/lib/elementary/efl_page_transition_scroll.c
@@ -62,7 +62,9 @@ _content_show(Efl_Page_Transition_Scroll_Data *pd,
    curr_page = efl_ui_pager_current_page_get(spd->pager.obj);
    cnt = efl_content_count(spd->pager.obj);
 
-   //FIXME make logic efficient: don't have to empty all and fill all the time
+   // at this point, the number of visible pages might have been changed,
+   // so empty all boxes and refill them with the right contents.
+   // FIXME make logic efficient: don't have to empty all and fill all the time
    EINA_LIST_FOREACH(pd->page_infos, list, pi)
      {
         if (pi->content)
@@ -133,6 +135,8 @@ _page_info_geometry_change(Efl_Page_Transition_Scroll_Data *pd,
 
    efl_gfx_geometry_set(pd->foreclip, (Eina_Rect) pd->viewport);
 
+   // this loop resets the geometry of each page based on the geometry of
+   // the pager object, the page size, and the padding size.
    EINA_LIST_FOREACH(pd->page_infos, list, pi)
      {
         EINA_RECTANGLE_SET(&pi->geometry,
@@ -274,11 +278,15 @@ _efl_page_transition_scroll_update(Eo *obj,
    curr_page = efl_ui_pager_current_page_get(spd->pager.obj);
    cnt = efl_content_count(spd->pager.obj);
 
+   // while pages are scrolled,
+   // 1. the geometry of each page needs to be changed
+   // 2. if a page gets out of the viewport, it needs to be hidden
+   // 3. if a page gets into the viewport, it needs to be shown
    EINA_LIST_FOREACH(pd->page_infos, list, pi)
      {
-        if (pos < 0)
+        if (pos < 0) // if scrolled right, each page takes next page's position
           tpi = pi->next;
-        else
+        else // else if scrolled left, each page takes prev page's position
           tpi = pi->prev;
 
 
@@ -352,6 +360,8 @@ _efl_page_transition_scroll_curr_page_change(Eo *obj EINA_UNUSED,
    Eina_List *list;
    Page_Info *pi, *target;
 
+   // after the current page is changed, page infos need to be updated
+   // with a new id based on the new geometry of the boxes.
    EINA_LIST_FOREACH(pd->page_infos, list, pi)
      {
         if (EINA_DBL_EQ(pos, 1.0))
@@ -455,6 +465,7 @@ _efl_page_transition_scroll_side_page_num_set(Eo *obj,
 
    if (delta > 0)
      {
+        // side_page_num is increased, so add boxes at both ends by the diff
         for (i = 0; i < delta; i++)
           {
              pi = calloc(1, sizeof(*pi));
@@ -490,6 +501,7 @@ _efl_page_transition_scroll_side_page_num_set(Eo *obj,
      }
    else
      {
+        // side_page_num is decreased, so remove boxes at both ends by the diff
         for (i = 0; i > delta; i--)
           {
              pi = pd->head;
diff --git a/src/lib/elementary/efl_page_transition_scroll.eo b/src/lib/elementary/efl_page_transition_scroll.eo
index 8ce91c0ee7..0bc5639124 100644
--- a/src/lib/elementary/efl_page_transition_scroll.eo
+++ b/src/lib/elementary/efl_page_transition_scroll.eo
@@ -1,8 +1,14 @@
 class Efl.Page.Transition.Scroll (Efl.Page.Transition)
 {
-   [[Efl ui pagescroller effect scroll class]]
+   [[Page transition for @Efl.Ui.Pager
+
+     With this type of transition, pages are arranged linearly and move parallel
+     to the screen by scrolling. The current page is displayed at center, and
+     previous and next pages might be displayed optionally.
+   ]]
    methods {
       @property side_page_num {
+         [[The number of pages displayed on each side of the current page]]
          values {
             side_page_num: int;
          }
diff --git a/src/lib/elementary/efl_page_transition_scroll.h b/src/lib/elementary/efl_page_transition_scroll.h
index af06123fc0..b4203d7706 100644
--- a/src/lib/elementary/efl_page_transition_scroll.h
+++ b/src/lib/elementary/efl_page_transition_scroll.h
@@ -3,6 +3,54 @@
 
 //#include "efl_ui_widget_pager.h"
 
+
+/**
+  * This is a description on how scroll transition works.
+  *
+  * Regardless of the number of pages, scroll transition maintains a fixed number
+  * of boxes which can contain pages. The boxes move along with scrolling and
+  * some of them are emptied or filled as they come in or out of screen area.
+  * When pager is scrolled left or right, each box takes the position of its
+  * previous or next box. Since the leftmost and rightmost boxes might move in
+  * reverse direction, they shouldn't be visible. This is why there are dummy
+  * boxes at both ends.
+  *
+  * Here is an example of box arrangement change by scrolling.
+  * The pager has 10 pages, numbered from 1 to 10.
+  * The current page is page5, and side_page_num equals 1.
+  *
+  *     head          |----- screen area ----|          tail
+  *    (dummy)        |                      |         (dummy)
+  *  ----------  ----------  ----------  ----------  ----------
+  *  |  BOX1  |  |  BOX2  |  |  BOX3  |  |  BOX4  |  |  BOX5  |
+  *  |        |  |        |  |        |  |        |  |        |
+  *  | (empty)|  |  page4 |  |  page5 |  |  page6 |  | (empty)|
+  *  |        |  |        |  |        |  |        |  |        |
+  *  |        |  |        |  |        |  |        |  |        |
+  *  |        |  |        |  |        |  |        |  |        |
+  *  ----------  ----------  ----------  ----------  ----------
+  *                   |                      |
+  *                   |----------------------|
+  *
+  * After scrolling left,
+  * 1. each box takes the position of it's previous box.
+  * 2. head and tail is changed.
+  * 3. The box moved to the end is emptied.
+  * 4. The box moved from the end is filled with content.
+  *
+  *     head                                            tail
+  *  ----------  ----------  ----------  ----------  ----------
+  *  |  BOX2  |  |  BOX3  |  |  BOX4  |  |  BOX5  |  |  BOX1  |
+  *  |        |  |        |  |        |  |        |  |        |
+  *  | (empty)|  |  page5 |  |  page6 |  |  page7 |  | (empty)|
+  *  |*emptied|  |        |  |        |  |*filled |  |        |
+  *  |        |  |        |  |        |  |        |  |        |
+  *  |        |  |        |  |        |  |        |  |        |
+  *  ----------  ----------  ----------  ----------  ----------
+  *
+  */
+
+
 typedef struct _Page_Info
 {
    Evas_Map                *map;
diff --git a/src/lib/elementary/efl_ui_pager.eo b/src/lib/elementary/efl_ui_pager.eo
index 2c1861291c..1a75e09027 100644
--- a/src/lib/elementary/efl_ui_pager.eo
+++ b/src/lib/elementary/efl_ui_pager.eo
@@ -7,39 +7,67 @@ enum Efl.Ui.Pager.Loop
 
 class Efl.Ui.Pager (Efl.Ui.Layout, Efl.Pack.Linear)
 {
-   [[Efl ui pager class]]
-   event_prefix: efl_ui_pager;
-   eo_prefix: efl_ui_pager;
+   [[Pager widget
+
+     A pager contains many pages in a linear fashion and allows users to scroll
+     through pages. Each page is numbered according to linear order and
+     one of the pages is marked as 'current page' and displayed in the middle.
+     The way each page is displayed is defined by @Efl.Page.Transition object,
+     allowing users to adopt different types of transition.
+     The most common use case of this widget is the home screen of mobile devices.
+   ]]
    methods {
       @property transition {
+         [[Page transition effect
+
+           Page transition is in charge of displaying pages in a specific way and
+           invoked every time page layout needs to be updated.
+         ]]
          set {
-            [[Page transition effect]]
+            [[Set a page transition effect]]
          }
          values {
             transition: Efl.Page.Transition @nonull; [[transition effect]]
          }
       }
       @property indicator {
+         [[Page indicator
+
+           Page indicator, located on the top layer of pager widget, helps users
+           to know the number of pages and the current page's index without scrolling.
+         ]]
          set {
-            [[Page indicator]]
+            [[Set a page indicator]]
          }
          values {
             klass: const(Efl.Class) @nullable; [[indicator class]]
          }
       }
       @property current_page {
-         [[Set the currently selected page]]
+         [[One page is selected as the current page and mainly displayed.]]
+         set {
+            [[Set one page as current page]]
+         }
+         get {
+            [[Get the current page]]
+         }
          values {
             index: int;
          }
       }
       @property scroll_block {
+         [[Pages can be scrolled back and forth by default. This property allows
+           limiting the direction of scrolling, or blocking scroll gesture at all.
+         ]]
          values {
             prev: bool;
             next: bool;
          }
       }
       @property loop_mode {
+         [[Pager is not scrolled after it's scrolled to the end by default.
+           This property gives the option to make a loop through pages.
+         ]]
          values {
             loop: Efl.Ui.Pager.Loop;
          }