docs: Update focus documentation

2 files changed, 52 insertions, 56 deletions

diff --git a/src/lib/elementary/efl_ui_focus_manager.eo b/src/lib/elementary/efl_ui_focus_manager.eo
index 14172a55f1..1b9798c77e 100644
--- a/src/lib/elementary/efl_ui_focus_manager.eo
+++ b/src/lib/elementary/efl_ui_focus_manager.eo
@@ -4,45 +4,45 @@ import eina_types;
 struct @beta @free(efl_ui_focus_relation_free) Efl.Ui.Focus.Relations {
     [[Structure holding the graph of relations between focusable objects.
     ]]
-    right : list<Efl.Ui.Focus.Object> @owned; [[List of objects on the right side]]
-    left : list<Efl.Ui.Focus.Object> @owned; [[List of objects on the left side]]
-    top : list<Efl.Ui.Focus.Object> @owned; [[List of objects above]]
-    down : list<Efl.Ui.Focus.Object> @owned; [[List of objects below]]
-    next : Efl.Ui.Focus.Object; [[Next object]]
-    prev : Efl.Ui.Focus.Object; [[Previous object]]
-    parent : Efl.Ui.Focus.Object; [[Parent object]]
-    redirect : Efl.Ui.Focus.Manager; [[Redirect manager]]
-    node : Efl.Ui.Focus.Object; [[The node where this is the information from]]
-    logical : bool; [[$true if this node is only logical]]
-    position_in_history : int; [[The position in the history stack]]
+    right : list<Efl.Ui.Focus.Object> @owned; [[List of objects to the right.]]
+    left : list<Efl.Ui.Focus.Object> @owned; [[List of objects to the left.]]
+    top : list<Efl.Ui.Focus.Object> @owned; [[List of objects above.]]
+    down : list<Efl.Ui.Focus.Object> @owned; [[List of objects below.]]
+    next : Efl.Ui.Focus.Object; [[Next object.]]
+    prev : Efl.Ui.Focus.Object; [[Previous object.]]
+    parent : Efl.Ui.Focus.Object; [[Parent object.]]
+    redirect : Efl.Ui.Focus.Manager; [[Redirect manager.]]
+    node : Efl.Ui.Focus.Object; [[The node where this information is from.]]
+    logical : bool; [[$true if this is a logical (non-regular) node.]]
+    position_in_history : int; [[The position in the history stack.]]
 }
 
 struct Efl.Ui.Focus.Manager_Logical_End_Detail {
-    [[Structure holding the focus object with extra information on logical end
+    [[Structure holding the focus object with extra information on logical end.
 
       @since 1.22
     ]]
     is_regular_end : bool; [[$true if element is registered as regular element in the @Efl.Ui.Focus.Manager object.]]
-    element : Efl.Ui.Focus.Object; [[The last element of the logical chain in the @Efl.Ui.Focus.Manager]]
+    element : Efl.Ui.Focus.Object; [[The last element of the logical chain in the @Efl.Ui.Focus.Manager.]]
 }
 
 interface Efl.Ui.Focus.Manager {
-    [[Interface for managing focus objects
+    [[Interface for managing focus objects.
 
       This interface is built in order to support movement of the focus property in a set of widgets.
       The movement of the focus property can happen in a tree manner, or a graph manner.
       The movement is also keeping track of the history of focused elements.
-      The tree interpretation differentiates between logical and non-logical widgets,
-      a logical widget cannot receive focus whereas a non-logical one can.
+      The tree interpretation differentiates between logical and regular widgets:
+      Logical widgets (typically containers) cannot receive focus, whereas Regular ones (like buttons) can.
 
       @since 1.22
     ]]
     methods {
         move {
-            [[Move the focus in the given direction.
+            [[Moves the focus in the given direction to the next regular widget.
 
               This call flushes all changes.
-              This means all changes between the last flush and now are computed.
+              This means all changes since last flush are computed.
             ]]
             params {
                 direction : Efl.Ui.Focus.Direction; [[The direction to move to.]]
@@ -50,22 +50,22 @@ interface Efl.Ui.Focus.Manager {
             return : Efl.Ui.Focus.Object; [[The element which is now focused.]]
         }
         request_move {
-            [[Return the object in the $direction from $child.]]
+            [[Returns the object in the $direction from $child.]]
             params {
                 direction : Efl.Ui.Focus.Direction; [[Direction to move focus.]]
                 child : Efl.Ui.Focus.Object; [[The child to move from.
                                                Pass $null to indicate the currently focused child.]]
-                logical : bool; [[Wether you want to have a logical node as result or a non-logical.
-                                  Note, in a @.move call no logical node will get focus.]]
+                logical : bool; [[Wether you want to have a logical node as result or a regular.
+                                  Note that in a @.move call logical nodes will not get focus.]]
             }
             return : Efl.Ui.Focus.Object; [[Object that would receive focus if moved in the given direction.]]
         }
         @property manager_focus {
-            [[The element which is currently focused by this manager
+            [[The element which is currently focused by this manager.
 
               Use this property to retrieve the object currently being focused, or to set the focus
               to a new one.
-              When $focus is a logical child (which cannot receive focus), the next non-logical
+              When $focus is a logical child (which cannot receive focus), the next regular
               object is selected instead. If there is no such object, focus does not change.
             ]]
 
@@ -81,14 +81,14 @@ interface Efl.Ui.Focus.Manager {
               anymore.
             ]]
             values {
-                redirect : Efl.Ui.Focus.Manager; [[The redirect manager.]]
+                redirect : Efl.Ui.Focus.Manager; [[The new focus manager.]]
             }
         }
         @property border_elements {
-            [[The list of elements which are at the border of the graph.
+            [[Elements which are at the border of the graph.
 
               This means one of the relations right,left or down,up are not set.
-              This call flushes all changes. See @Efl.Ui.Focus.Manager.move
+              This call flushes all changes. See @Efl.Ui.Focus.Manager.move.
             ]]
             get {}
             values {
@@ -97,7 +97,7 @@ interface Efl.Ui.Focus.Manager {
             }
         }
         @property viewport_elements {
-            [[Get all elements that are at the border of the viewport
+            [[Elements that are at the border of the viewport
 
               Every element returned by this is located inside the viewport rectangle,
               but has a right, left, down or up neighbor outside the viewport.
@@ -107,7 +107,7 @@ interface Efl.Ui.Focus.Manager {
                 viewport : Eina.Rect; [[The rectangle defining the viewport.]]
             }
             values {
-              viewport_elements : iterator<Efl.Ui.Focus.Object>; [[The list of border objects.]]
+              viewport_elements : iterator<Efl.Ui.Focus.Object>; [[An iterator over the viewport border objects.]]
             }
         }
         @property root {
@@ -116,21 +116,19 @@ interface Efl.Ui.Focus.Manager {
               This property can only be set once.
             ]]
             set {
-                return : bool; [[If $true, this is the root node]]
+                return : bool; [[$true on success, $false if it had already been set.]]
             }
-
             get {}
 
             values {
-                root : Efl.Ui.Focus.Object; [[Will be registered into
-                    this manager object.]]
+                root : Efl.Ui.Focus.Object; [[Object to register as the root of this manager object.]]
             }
         }
         request_subchild {
-            [[Return the widget in the direction next.
+            [[Returns the widget in the direction next.
 
               The returned widget is a child of $root.
-              It's guaranteed that child will not be prepared once again,
+              It's guaranteed that child will not be prepared again,
               so you can call this function inside a @Efl.Ui.Focus.Object.setup_order call.
             ]]
               params {
@@ -139,9 +137,9 @@ interface Efl.Ui.Focus.Manager {
               return : Efl.Ui.Focus.Object; [[Child of passed parameter.]]
         }
         fetch @beta {
-            [[This will fetch the data from a registered node.
+            [[Fetches the data from a registered node.
 
-              Be aware this function will trigger a computation of all dirty nodes.
+              Note: This function triggers a computation of all dirty nodes.
             ]]
             params {
                 child : Efl.Ui.Focus.Object; [[The child object to inspect.]]
@@ -150,7 +148,7 @@ interface Efl.Ui.Focus.Manager {
                 starting from $child.]]
         }
         logical_end {
-            [[Return the last logical object.
+            [[Returns the last logical object.
 
               The returned object is the last object that would be returned if you start at the root
               and move in the "next" direction.
@@ -158,7 +156,7 @@ interface Efl.Ui.Focus.Manager {
             return : Efl.Ui.Focus.Manager_Logical_End_Detail; [[Last object.]]
         }
         reset_history {
-            [[Reset the history stack of this manager object.
+            [[Resets the history stack of this manager object.
               This means the uppermost element will be unfocused, and all other elements
               will be removed from the remembered list.
 
@@ -167,7 +165,7 @@ interface Efl.Ui.Focus.Manager {
             ]]
         }
         pop_history_stack {
-            [[Remove the uppermost history element, and focus the previous one.
+            [[Removes the uppermost history element, and focuses the previous one.
 
               If there is an element that was focused before, it will be used.
               Otherwise, the best fitting element from the registered elements will be focused.
@@ -176,7 +174,7 @@ interface Efl.Ui.Focus.Manager {
         setup_on_first_touch {
            [[Called when this manager is set as redirect.
 
-             In case that this is called as an result of a move call, $direction and $entry
+             In case that this is called as a result of a move call, $direction and $entry
              will be set to the direction of the move call, and the $entry object will be
              set to the object that had this manager as redirect property.
            ]]
@@ -186,17 +184,17 @@ interface Efl.Ui.Focus.Manager {
            }
         }
         dirty_logic_freeze {
-          [[This disables the cache invalidation when an object is moved.
+          [[Disables the cache invalidation when an object is moved.
 
             Even if an object is moved, the focus manager will not recalculate its relations.
             This can be used when you know that the set of widgets in the focus manager is
             moved the same way, so the relations between the widgets in the set do not change
-            and the complex calculations can be avoided.
+            and complex calculations can be avoided.
             Use @.dirty_logic_unfreeze to re-enable relationship calculation.
           ]]
         }
         dirty_logic_unfreeze {
-          [[This enables the cache invalidation when an object is moved.
+          [[Enables the cache invalidation when an object is moved.
 
             This is the counterpart to @.dirty_logic_freeze.
           ]]
diff --git a/src/lib/elementary/efl_ui_focus_object.eo b/src/lib/elementary/efl_ui_focus_object.eo
index 77e1f81466..23248804d6 100644
--- a/src/lib/elementary/efl_ui_focus_object.eo
+++ b/src/lib/elementary/efl_ui_focus_object.eo
@@ -33,17 +33,17 @@ mixin Efl.Ui.Focus.Object
         }
         @property focus_manager {
             [[This is the focus manager where this focus object is registered in.
-              The element which is the $root of a Efl.Ui.Focus.Manager will not
-              have this focus manager as this object, but rather the second focus
-              manager where it is registered in.
+              The element which is the $root of an @Efl.Ui.Focus.Manager will not
+              have this focus manager as this object, but rather the focus manager
+              where that is registered in.
             ]]
             get {}
             values {
-                manager : Efl.Ui.Focus.Manager; [[The manager object]]
+                manager : Efl.Ui.Focus.Manager; [[The manager object.]]
             }
         }
         @property focus_parent {
-            [[Describes which logical parent is used by this object.]]
+            [[The logical parent used by this object.]]
             get {}
             values {
                 logical_parent : Efl.Ui.Focus.Object; [[The focus parent.]]
@@ -57,8 +57,8 @@ mixin Efl.Ui.Focus.Object
         }
         setup_order {
             [[Tells the object that its children will be queried soon by the focus manager.
-              Overwrite this to update the order of the children. Deleting items in this call will
-              result in undefined behaviour and may cause your system to crash.
+              Overwrite this to have a chance to update the order of the children.
+              Deleting items in this call will result in undefined behaviour and may cause your system to crash.
             ]]
         }
         setup_order_non_recursive @protected {
@@ -66,8 +66,8 @@ mixin Efl.Ui.Focus.Object
               additional recursive calls to @.setup_order will not call this function again.]]
         }
         on_focus_update @protected {
-           [[Virtual function handling focus in/out events on the widget]]
-           return: bool; [[$true if this widget can handle focus, $false otherwise]]
+           [[Virtual function handling focus in/out events on the widget.]]
+           return: bool; [[$true if this widget can handle focus, $false otherwise.]]
         }
     }
     implements {
@@ -79,10 +79,8 @@ mixin Efl.Ui.Focus.Object
     }
     events {
         focus,changed : bool; [[Emitted if the focus state has changed.]]
-        focus_manager,changed: Efl.Ui.Focus.Manager; [[Emitted when a new manager is
-                                                 the parent for this object.]]
-        focus_parent,changed: Efl.Ui.Focus.Object; [[Emitted when a new logical
-                                                parent should be used.]]
+        focus_manager,changed: Efl.Ui.Focus.Manager; [[Emitted when a new manager is the parent for this object.]]
+        focus_parent,changed: Efl.Ui.Focus.Object; [[Emitted when a new logical parent should be used.]]
         child_focus,changed: bool; [[Emitted if child_focus has changed.]]
         focus_geometry,changed: Eina.Rect; [[Emitted if focus geometry of this object has changed.]]
     }