efl/wl: add docs for surface object and re-namespace

Summary: Depends on D11501

Reviewers: segfaultxavi

Reviewed By: segfaultxavi

Subscribers: cedric, #reviewers, #committers

Tags: #efl

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

2 files changed, 47 insertions, 13 deletions

diff --git a/src/lib/efl_canvas_wl/efl_canvas_wl.eo b/src/lib/efl_canvas_wl/efl_canvas_wl.eo
index 4b0e4fa353..4481ef4f12 100644
--- a/src/lib/efl_canvas_wl/efl_canvas_wl.eo
+++ b/src/lib/efl_canvas_wl/efl_canvas_wl.eo
@@ -26,7 +26,7 @@ class @beta Efl.Canvas.Wl extends Efl.Canvas.Group
    [[A multiseat xdg-shell compliant Wayland compositor which runs in a canvas object.
 
      All toplevel windows will be sized to the size of the compositor object unless extracted with
-     @Efl.Canvas.Wl.Surface.extract.
+     @Efl.Canvas.Wl_Surface.extract.
 
      Only clients executed with @Efl.Canvas.Wl.run or added with @.allowed_pid_add will
      be permitted to connect to this compositor.
@@ -82,11 +82,11 @@ class @beta Efl.Canvas.Wl extends Efl.Canvas.Group
       }
       surface_next {
          [[Activate and raise the bottom-most toplevel surface.]]
-         return: Efl.Canvas.Wl.Surface; [[The surface that was activated, or $NULL if no change was made.]]
+         return: Efl.Canvas.Wl_Surface; [[The surface that was activated, or $NULL if no change was made.]]
       }
       surface_prev {
          [[Activate and raise the second top-most toplevel surface.]]
-         return: Efl.Canvas.Wl.Surface; [[The surface that was activated, or $NULL if no change was made.]]
+         return: Efl.Canvas.Wl_Surface; [[The surface that was activated, or $NULL if no change was made.]]
       }
       @property active_surface {
          [[This is the currently activated surface in the compositor widget.
@@ -97,7 +97,7 @@ class @beta Efl.Canvas.Wl extends Efl.Canvas.Group
             return: bool; [[Returns $true if a change was successfully made.]]
          }
          values {
-            surface: Efl.Canvas.Wl.Surface; [[The activated surface.]]
+            surface: Efl.Canvas.Wl_Surface; [[The activated surface.]]
          }
       }
       @property aspect_propagate {
@@ -175,9 +175,9 @@ class @beta Efl.Canvas.Wl extends Efl.Canvas.Group
       Efl.Gfx.Entity.scale { get; set; }
    }
    events {
-      toplevel,added: Efl.Canvas.Wl.Surface; [[Contains the toplevel surface which was added.]]
-      child,added: Efl.Canvas.Wl.Surface; [[Contains the toplevel child surface which was added.]]
-      popup,added: Efl.Canvas.Wl.Surface; [[Contains the popup surface which was added.]]
+      toplevel,added: Efl.Canvas.Wl_Surface; [[Contains the toplevel surface which was added.]]
+      child,added: Efl.Canvas.Wl_Surface; [[Contains the toplevel child surface which was added.]]
+      popup,added: Efl.Canvas.Wl_Surface; [[Contains the popup surface which was added.]]
       seat,added: Efl.Input.Device; [[Contains the seat object that was added.]]
    }
 }
diff --git a/src/lib/efl_canvas_wl/efl_canvas_wl_surface.eo b/src/lib/efl_canvas_wl/efl_canvas_wl_surface.eo
index f2a351becc..d2646f8431 100644
--- a/src/lib/efl_canvas_wl/efl_canvas_wl_surface.eo
+++ b/src/lib/efl_canvas_wl/efl_canvas_wl_surface.eo
@@ -1,27 +1,61 @@
-class @beta Efl.Canvas.Wl.Surface extends Efl.Canvas.Group
+class @beta Efl.Canvas.Wl_Surface extends Efl.Canvas.Group
 {
-   [[@since 1.24]]
+   [[A canvas object representing a Wayland toplevel or popup surface.
+
+     This object's geometry properties reflect the properties of the underlying surface. If
+     the client is using a protocol to export its size hints, those hints will be directly
+     applied to this object any time they change in the application.
+
+     Changes to geometry and visibility of this object must not be made while @.extracted
+     is $false.
+
+     Changes to size of this object will be immediately propagated to the underlying application.
+
+     Hiding this object will have differing effects based on the surface's xdg-shell role.
+     If the surface is a popup, it will be sent the 'done' protocol event which will close it.
+     If the surface is a toplevel, it will be deactivated if it was active.
+
+     This object's lifetime is bound to the lifetime of the underlying surface or the compositor widget.
+
+     This object must not be manually deleted.
+     @since 1.24
+   ]]
    data: Comp_Surface;
    methods {
       extract {
-         return: bool;
+         [[Extract a surface from the compositor widget.
+
+           Call this prior to making any calls which directly modify the geometry of
+           the surface. Once extracted, the compositor will no longer attempt to automatically
+           apply geometry or stacking changes to the surface.
+
+           Once extracted, a surface cannot be un-extracted.
+         ]]
+         return: bool; [[Returns $true if the surface was successfully extracted.]]
       }
       @property pid {
+         [[The process id of the surface's application.]]
          get {}
          values {
-            pid: int;
+            pid: int; [[The process id, or -1 if the surface has been asynchronously destroyed.]]
          }
       }
       @property parent_surface {
+         [[The parent surface of the given surface. This value is $NULL for toplevel surfaces without a parent.
+
+           For popup surfaces, this may be another popup or a toplevel.
+           For toplevel surfaces, this will always be another toplevel or $NULL.
+         ]]
          get {}
          values {
-            parent: Efl.Canvas.Wl.Surface;
+            parent: Efl.Canvas.Wl_Surface; [[The parent surface. $NULL if no parent exists or the surface was asynchronously destroyed.]]
          }
       }
       @property extracted {
+         [[The extracted state of the surface.]]
          get {}
          values {
-            extracted: bool;
+            extracted: bool; [[$true if @.extract was successfully called previously.]]
          }
       }
    }