docs: Reword Efl.Container and family

Summary:
Avoid using "Item" since this is used by Grid and List items, or "Child" since
this is what Efl.Object uses.
Also clarify what each container does.

Test Plan: Only changes in docs. Everything still builds and passes tests.

Reviewers: bu5hm4n, cedric, zmike

Reviewed By: bu5hm4n

Subscribers: #reviewers, #committers

Tags: #efl

Differential Revision: https://phab.enlightenment.org/D8720

diff --git a/src/lib/efl/interfaces/efl_container.eo b/src/lib/efl/interfaces/efl_container.eo
index d45d0a1..e308e2e 100644 (file)
--- a/src/lib/efl/interfaces/efl_container.eo
+++ b/src/lib/efl/interfaces/efl_container.eo
@@ -1,8 +1,8 @@
 interface Efl.Container
 {
-   [[Common interface for objects that have multiple contents (sub objects).
+   [[Common interface for objects (containers) that can have multiple contents (sub-objects).
 
-     APIs in this interface deal with containers of multiple sub objects, not
+     APIs in this interface deal with containers of multiple sub-objects, not
      with individual parts.
 
      @since 1.22
@@ -12,15 +12,15 @@ interface Efl.Container
    methods {
       content_iterate {
          [[Begin iterating over this object's contents.]]
-         return: iterator<Efl.Gfx.Entity> @owned @warn_unused; [[Iterator to object content]]
+         return: iterator<Efl.Gfx.Entity> @owned @warn_unused; [[Iterator on object's content.]]
       }
       content_count {
-         [[Returns the number of UI elements packed in this container.]]
-         return: int; [[Number of packed UI elements]]
+         [[Returns the number of contained sub-objects.]]
+         return: int; [[Number of sub-objects.]]
       }
    }
    events {
-      content,added: Efl.Gfx.Entity;    [[Sent after a new item was added.]]
-      content,removed: Efl.Gfx.Entity;  [[Sent after an item was removed, before unref.]]
+      content,added: Efl.Gfx.Entity;    [[Sent after a new sub-object was added.]]
+      content,removed: Efl.Gfx.Entity;  [[Sent after a sub-object was removed, before unref.]]
    }
 }

diff --git a/src/lib/efl/interfaces/efl_pack.eo b/src/lib/efl/interfaces/efl_pack.eo
index f6a9b3a..39f686e 100644 (file)
--- a/src/lib/efl/interfaces/efl_pack.eo
+++ b/src/lib/efl/interfaces/efl_pack.eo
@@ -1,28 +1,30 @@
 interface @beta Efl.Pack extends Efl.Container
 {
-   [[API common to all UI container objects.]]
+   [[Common interface for objects (containers) with multiple contents
+     (sub-objects) which can be added and removed at runtime.
+   ]]
    methods
    {
       pack_clear {
-         [[Removes all packed contents, and unreferences them.]]
-         return: bool; [[$true on success, $false otherwise]]
+         [[Removes all packed sub-objects and unreferences them.]]
+         return: bool; [[$true on success, $false otherwise.]]
       }
       unpack_all {
-         [[Removes all packed contents, without unreferencing them.
+         [[Removes all packed sub-objects without unreferencing them.
 
            Use with caution.
          ]]
-         return: bool; [[$true on success, $false otherwise]]
+         return: bool; [[$true on success, $false otherwise.]]
       }
       unpack {
-         [[Removes an existing item from the container, without deleting it.]]
+         [[Removes an existing sub-object from the container without deleting it.]]
          params {
-            subobj: Efl.Gfx.Entity; [[The unpacked object.]]
+            subobj: Efl.Gfx.Entity; [[The sub-object to unpack.]]
          }
-         return: bool; [[$false if $subobj wasn't a child or can't be removed]]
+         return: bool; [[$false if $subobj wasn't in the container or couldn't be removed.]]
       }
       pack {
-         [[Adds an item to this container.
+         [[Adds a sub-object to this container.
 
            Depending on the container this will either fill in the default
            spot, replacing any already existing element or append to the end
@@ -33,7 +35,7 @@ interface @beta Efl.Pack extends Efl.Container
            without deleting it.
          ]]
          params {
-            subobj: Efl.Gfx.Entity; [[An object to pack.]]
+            subobj: Efl.Gfx.Entity; [[The object to pack.]]
          }
          return: bool; [[$false if $subobj could not be packed.]]
       }

diff --git a/src/lib/efl/interfaces/efl_pack_linear.eo b/src/lib/efl/interfaces/efl_pack_linear.eo
index b82cee8..b98d3ec 100644 (file)
--- a/src/lib/efl/interfaces/efl_pack_linear.eo
+++ b/src/lib/efl/interfaces/efl_pack_linear.eo
@@ -1,6 +1,10 @@
 interface @beta Efl.Pack_Linear extends Efl.Pack
 {
-   [[API for containers ]]
+   [[Common interface for objects (containers) with multiple contents
+     (sub-objects) which can be added and removed at runtime in a linear fashion.
+
+     This means the sub-objects are internally organized in an ordered list.
+   ]]
    eo_prefix: efl_pack;
    methods {
       pack_begin {
@@ -13,12 +17,12 @@ interface @beta Efl.Pack_Linear extends Efl.Pack
            container without deleting it.
          ]]
          params {
-            @in subobj: Efl.Gfx.Entity; [[Item to pack at the beginning.]]
+            @in subobj: Efl.Gfx.Entity; [[Object to pack at the beginning.]]
          }
          return: bool; [[$false if $subobj could not be packed.]]
       }
       pack_end {
-         [[Append item at the end of this container.
+         [[Append object at the end of this container.
 
            This is the same as @.pack_at($subobj, -1).
 
@@ -27,45 +31,46 @@ interface @beta Efl.Pack_Linear extends Efl.Pack
            container without deleting it.
          ]]
          params {
-            @in subobj: Efl.Gfx.Entity; [[Item to pack at the end.]]
+            @in subobj: Efl.Gfx.Entity; [[Object to pack at the end.]]
          }
          return: bool; [[$false if $subobj could not be packed.]]
       }
       pack_before {
-         [[Prepend item before other sub object.
+         [[Prepend an object before an existing sub-object.
 
            When this container is deleted, it will request deletion of the
            given $subobj. Use @Efl.Pack.unpack to remove $subobj from this
            container without deleting it.
          ]]
          params {
-            @in subobj: Efl.Gfx.Entity; [[Item to pack before $existing.]]
-            @in existing: const(Efl.Gfx.Entity); [[Item to refer to.]]
+            @in subobj: Efl.Gfx.Entity; [[Object to pack before $existing.]]
+            @in existing: const(Efl.Gfx.Entity); [[Existing reference sub-object.]]
          }
          return: bool; [[$false if $existing could not be found or $subobj
                          could not be packed.]]
       }
       pack_after {
-         [[Append item after other sub object.
+         [[Append an object after an existing sub-object.
 
            When this container is deleted, it will request deletion of the
            given $subobj. Use @Efl.Pack.unpack to remove $subobj from this
            container without deleting it.
          ]]
          params {
-            @in subobj: Efl.Gfx.Entity; [[Item to pack after $existing.]]
-            @in existing: const(Efl.Gfx.Entity); [[Item to refer to.]]
+            @in subobj: Efl.Gfx.Entity; [[Object to pack after $existing.]]
+            @in existing: const(Efl.Gfx.Entity); [[Existing reference sub-object.]]
          }
          return: bool; [[$false if $existing could not be found or $subobj
                          could not be packed.]]
       }
       pack_at {
-          [[Inserts $subobj BEFORE the item at position $index.
+          [[Inserts $subobj BEFORE the sub-object at position $index.
 
             $index ranges from -$count to $count-1, where positive numbers go
-            from first item (0) to last item ($count-1), and negative numbers go
-            from last item (-1) to first item (-$count). Where $count is
-            the number of items currently in the container.
+            from first sub-object (0) to last ($count-1), and negative numbers go
+            from last sub-object (-1) to first (-$count). $count is
+            the number of sub-objects currently in the container as returned by
+            @Efl.Container.content_count.
 
             If $index is less than -$count, it will trigger @.pack_begin($subobj)
             whereas $index greater than $count-1 will trigger @.pack_end($subobj).
@@ -75,59 +80,59 @@ interface @beta Efl.Pack_Linear extends Efl.Pack
             container without deleting it.
           ]]
           params {
-             @in subobj: Efl.Gfx.Entity; [[Item to pack.]]
-             @in index:  int; [[Index of item to insert BEFORE.
+             @in subobj: Efl.Gfx.Entity; [[Object to pack.]]
+             @in index:  int; [[Index of existing sub-object to insert BEFORE.
                                 Valid range is -$count to ($count-1).
                               ]]
           }
           return: bool; [[$false if $subobj could not be packed.]]
       }
       pack_content_get {
-         [[Content at a given $index in this container.
+         [[Sub-object at a given $index in this container.
 
            $index ranges from -$count to $count-1, where positive numbers go
-           from first item (0) to last item ($count-1), and negative numbers go
-           from last item (-1) to first item (-$count). Where $count is
-           the number of items currently in the container.
+           from first sub-object (0) to last ($count-1), and negative numbers go
+           from last sub-object (-1) to first (-$count). $count is
+           the number of sub-objects currently in the container as returned by
+           @Efl.Container.content_count.
 
-           If $index is less than -$count, it will return the first item
-           whereas $index greater than $count-1 will return the last item.
+           If $index is less than -$count, it will return the first sub-object
+           whereas $index greater than $count-1 will return the last sub-object.
          ]]
          params {
-            @in index: int; [[Index of the item to retrieve.
+            @in index: int; [[Index of the existing sub-object to retrieve.
                               Valid range is -$count to ($count-1).
                             ]]
          }
-         return: Efl.Gfx.Entity; [[The object contained at the given $index.]]
+         return: Efl.Gfx.Entity; [[The sub-object contained at the given $index.]]
       }
       pack_index_get {
-         [[Get the index of a child in this container.]]
+         [[Get the index of a sub-object in this container.]]
          params {
-            @in subobj: const(Efl.Gfx.Entity); [[An object contained in this pack.]]
+            @in subobj: const(Efl.Gfx.Entity); [[An existing sub-object in this container.]]
          }
-         return: int(-1); [[-1 in case $subobj is not a child of this object,
-                            or the index of this item in the range 0 to ($count-1).
+         return: int(-1); [[-1 in case $subobj is not found,
+                            or the index of $subobj in the range 0 to ($count-1).
                           ]]
       }
       pack_unpack_at {
-         [[Pop out (remove) the item at the specified $index.
+         [[Pop out (remove) the sub-object at the specified $index.
 
            $index ranges from -$count to $count-1, where positive numbers go
-           from first item (0) to last item ($count-1), and negative numbers go
-           from last item (-1) to first item (-$count). Where $count is
-           the number of items currently in the container.
-
-           If $index is less than -$count, it will remove the first item
-           whereas $index greater than $count-1 will remove the last item.
+           from first sub-object (0) to last ($count-1), and negative numbers go
+           from last sub-object (-1) to first (-$count). $count is
+           the number of sub-objects currently in the container as returned by
+           @Efl.Container.content_count.
 
-           Equivalent to @Efl.Pack.unpack(@.pack_content_get($index)).
+           If $index is less than -$count, it will remove the first sub-object
+           whereas $index greater than $count-1 will remove the last sub-object.
          ]]
          params {
-            @in index: int; [[Index of item to remove.
+            @in index: int; [[Index of the sub-object to remove.
                               Valid range is -$count to ($count-1).
                             ]]
          }
-         return: Efl.Gfx.Entity; [[The child item if it could be removed.]]
+         return: Efl.Gfx.Entity; [[The sub-object if it could be removed.]]
       }
    }
 }