xdg-foreign-v2: Fix various documentation issues from the API change

Submitted by Jonas Ådahl on Sept. 26, 2017, 1:53 p.m.

Details

Message ID 20170926135351.26877-1-jadahl@gmail.com
State New
Headers show
Series "Series without cover letter" ( rev: 2 ) in Wayland

Not browsing as part of any series.

Commit Message

Jonas Ådahl Sept. 26, 2017, 1:53 p.m.
It stilled referred to the removed requests, so change those places to
refer to the renamed ones.

While at it, also change documentation to refer directly to
xdg_toplevel, as that has now been introduced.

Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
---

Hi,

On Tue, Sep 26, 2017 at 03:06:05PM +0200, Marco Martin wrote:
> ping?
> 

The API change looks good to me, but the documentation was left
unchanged, thus incorrect. I fixed it in this patch. Please take a look.

Locally I did some minor commit message changes to your patches. For
example I changed the commit message to say 'xdg-foreign' not just
'foreign', as well as some minor similar cosmetic issues.


Jonas




 unstable/xdg-foreign/xdg-foreign-unstable-v2.xml | 30 ++++++++++++------------
 1 file changed, 15 insertions(+), 15 deletions(-)

Patch hide | download patch | download mbox

diff --git a/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml b/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
index 8e824c1..bf46fa8 100644
--- a/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
+++ b/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
@@ -32,12 +32,12 @@ 
     some of its own surface above the other clients surface.
 
     In order for a client A to get a reference of a surface of client B, client
-    B must first export its surface using xdg_exporter.export. Upon doing this,
-    client B will receive a handle (a unique string) that it may share with
-    client A in some way (for example D-Bus). After client A has received the
-    handle from client B, it may use xdg_importer.import to create a reference
-    to the surface client B just exported. See the corresponding requests for
-    details.
+    B must first export its surface using xdg_exporter.export_toplevel. Upon
+    doing this, client B will receive a handle (a unique string) that it may
+    share with client A in some way (for example D-Bus). After client A has
+    received the handle from client B, it may use xdg_importer.import_toplevel
+    to create a reference to the surface client B just exported. See the
+    corresponding requests for details.
 
     A possible use case for this is out-of-process dialogs. For example when a
     sandboxed client without file system access needs the user to select a file
@@ -77,8 +77,8 @@ 
 	corresponding interface and event for details.
 
 	A surface may be exported multiple times, and each exported handle may
-	be used to create a xdg_imported multiple times. Only xdg_surface
-	surfaces may be exported.
+	be used to create a xdg_imported multiple times. Only xdg_toplevel
+	equivalent surfaces may be exported.
       </description>
       <arg name="id" type="new_id" interface="zxdg_exported_v2"
 	   summary="the new xdg_exported object"/>
@@ -104,8 +104,8 @@ 
     <request name="import_toplevel">
       <description summary="import a toplevel surface">
 	The import_toplevel request imports a surface from any client given a handle
-	retrieved by exporting said surface using xdg_exporter.export. When
-	called, a new xdg_imported object will be created. This new object
+	retrieved by exporting said surface using xdg_exporter.export_toplevel.
+	When called, a new xdg_imported object will be created. This new object
 	represents the imported surface, and the importing client can
 	manipulate its relationship using it. See xdg_imported for details.
       </description>
@@ -136,8 +136,8 @@ 
       <description summary="the exported surface handle">
 	The handle event contains the unique handle of this exported surface
 	reference. It may be shared with any client, which then can use it to
-	import the surface by calling xdg_importer.import. A handle may be
-	used to import the surface multiple times.
+	import the surface by calling xdg_importer.import_toplevel. A handle
+	may be used to import the surface multiple times.
       </description>
       <arg name="handle" type="string" summary="the exported surface handle"/>
     </event>
@@ -161,9 +161,9 @@ 
     <request name="set_parent_of">
       <description summary="set as the parent of some surface">
 	Set the imported surface as the parent of some surface of the client.
-	The passed surface must be a toplevel xdg_surface. Calling this function
-	sets up a surface to surface relation with the same stacking and positioning
-	semantics as xdg_surface.set_parent.
+	The passed surface must be a xdg_toplevel equivalent. Calling this
+	function sets up a surface to surface relation with the same stacking
+	and positioning semantics as xdg_toplevel.set_parent.
       </description>
       <arg name="surface" type="object" interface="wl_surface"
 	   summary="the child surface"/>

Comments

Changes look fine to me, in the end my patches would be pushed as is
and then this one pushed on top, right?

--
Marco Martin

On Tue, Sep 26, 2017 at 3:53 PM, Jonas Ådahl <jadahl@gmail.com> wrote:
> It stilled referred to the removed requests, so change those places to
> refer to the renamed ones.
>
> While at it, also change documentation to refer directly to
> xdg_toplevel, as that has now been introduced.
>
> Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
> ---
>
> Hi,
>
> On Tue, Sep 26, 2017 at 03:06:05PM +0200, Marco Martin wrote:
>> ping?
>>
>
> The API change looks good to me, but the documentation was left
> unchanged, thus incorrect. I fixed it in this patch. Please take a look.
>
> Locally I did some minor commit message changes to your patches. For
> example I changed the commit message to say 'xdg-foreign' not just
> 'foreign', as well as some minor similar cosmetic issues.
>
>
> Jonas
>
>
>
>
>  unstable/xdg-foreign/xdg-foreign-unstable-v2.xml | 30 ++++++++++++------------
>  1 file changed, 15 insertions(+), 15 deletions(-)
>
> diff --git a/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml b/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
> index 8e824c1..bf46fa8 100644
> --- a/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
> +++ b/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
> @@ -32,12 +32,12 @@
>      some of its own surface above the other clients surface.
>
>      In order for a client A to get a reference of a surface of client B, client
> -    B must first export its surface using xdg_exporter.export. Upon doing this,
> -    client B will receive a handle (a unique string) that it may share with
> -    client A in some way (for example D-Bus). After client A has received the
> -    handle from client B, it may use xdg_importer.import to create a reference
> -    to the surface client B just exported. See the corresponding requests for
> -    details.
> +    B must first export its surface using xdg_exporter.export_toplevel. Upon
> +    doing this, client B will receive a handle (a unique string) that it may
> +    share with client A in some way (for example D-Bus). After client A has
> +    received the handle from client B, it may use xdg_importer.import_toplevel
> +    to create a reference to the surface client B just exported. See the
> +    corresponding requests for details.
>
>      A possible use case for this is out-of-process dialogs. For example when a
>      sandboxed client without file system access needs the user to select a file
> @@ -77,8 +77,8 @@
>         corresponding interface and event for details.
>
>         A surface may be exported multiple times, and each exported handle may
> -       be used to create a xdg_imported multiple times. Only xdg_surface
> -       surfaces may be exported.
> +       be used to create a xdg_imported multiple times. Only xdg_toplevel
> +       equivalent surfaces may be exported.
>        </description>
>        <arg name="id" type="new_id" interface="zxdg_exported_v2"
>            summary="the new xdg_exported object"/>
> @@ -104,8 +104,8 @@
>      <request name="import_toplevel">
>        <description summary="import a toplevel surface">
>         The import_toplevel request imports a surface from any client given a handle
> -       retrieved by exporting said surface using xdg_exporter.export. When
> -       called, a new xdg_imported object will be created. This new object
> +       retrieved by exporting said surface using xdg_exporter.export_toplevel.
> +       When called, a new xdg_imported object will be created. This new object
>         represents the imported surface, and the importing client can
>         manipulate its relationship using it. See xdg_imported for details.
>        </description>
> @@ -136,8 +136,8 @@
>        <description summary="the exported surface handle">
>         The handle event contains the unique handle of this exported surface
>         reference. It may be shared with any client, which then can use it to
> -       import the surface by calling xdg_importer.import. A handle may be
> -       used to import the surface multiple times.
> +       import the surface by calling xdg_importer.import_toplevel. A handle
> +       may be used to import the surface multiple times.
>        </description>
>        <arg name="handle" type="string" summary="the exported surface handle"/>
>      </event>
> @@ -161,9 +161,9 @@
>      <request name="set_parent_of">
>        <description summary="set as the parent of some surface">
>         Set the imported surface as the parent of some surface of the client.
> -       The passed surface must be a toplevel xdg_surface. Calling this function
> -       sets up a surface to surface relation with the same stacking and positioning
> -       semantics as xdg_surface.set_parent.
> +       The passed surface must be a xdg_toplevel equivalent. Calling this
> +       function sets up a surface to surface relation with the same stacking
> +       and positioning semantics as xdg_toplevel.set_parent.
>        </description>
>        <arg name="surface" type="object" interface="wl_surface"
>            summary="the child surface"/>
> --
> 2.13.5
>
ping? shouldn't the 3 patches in total be pushed now?

--
Marco Martin

On Tue, Sep 26, 2017 at 3:53 PM, Jonas Ådahl <jadahl@gmail.com> wrote:
> It stilled referred to the removed requests, so change those places to
> refer to the renamed ones.
>
> While at it, also change documentation to refer directly to
> xdg_toplevel, as that has now been introduced.
>
> Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
> ---
>
> Hi,
>
> On Tue, Sep 26, 2017 at 03:06:05PM +0200, Marco Martin wrote:
>> ping?
>>
>
> The API change looks good to me, but the documentation was left
> unchanged, thus incorrect. I fixed it in this patch. Please take a look.
>
> Locally I did some minor commit message changes to your patches. For
> example I changed the commit message to say 'xdg-foreign' not just
> 'foreign', as well as some minor similar cosmetic issues.
>
>
> Jonas
>
>
>
>
>  unstable/xdg-foreign/xdg-foreign-unstable-v2.xml | 30 ++++++++++++------------
>  1 file changed, 15 insertions(+), 15 deletions(-)
>
> diff --git a/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml b/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
> index 8e824c1..bf46fa8 100644
> --- a/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
> +++ b/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
> @@ -32,12 +32,12 @@
>      some of its own surface above the other clients surface.
>
>      In order for a client A to get a reference of a surface of client B, client
> -    B must first export its surface using xdg_exporter.export. Upon doing this,
> -    client B will receive a handle (a unique string) that it may share with
> -    client A in some way (for example D-Bus). After client A has received the
> -    handle from client B, it may use xdg_importer.import to create a reference
> -    to the surface client B just exported. See the corresponding requests for
> -    details.
> +    B must first export its surface using xdg_exporter.export_toplevel. Upon
> +    doing this, client B will receive a handle (a unique string) that it may
> +    share with client A in some way (for example D-Bus). After client A has
> +    received the handle from client B, it may use xdg_importer.import_toplevel
> +    to create a reference to the surface client B just exported. See the
> +    corresponding requests for details.
>
>      A possible use case for this is out-of-process dialogs. For example when a
>      sandboxed client without file system access needs the user to select a file
> @@ -77,8 +77,8 @@
>         corresponding interface and event for details.
>
>         A surface may be exported multiple times, and each exported handle may
> -       be used to create a xdg_imported multiple times. Only xdg_surface
> -       surfaces may be exported.
> +       be used to create a xdg_imported multiple times. Only xdg_toplevel
> +       equivalent surfaces may be exported.
>        </description>
>        <arg name="id" type="new_id" interface="zxdg_exported_v2"
>            summary="the new xdg_exported object"/>
> @@ -104,8 +104,8 @@
>      <request name="import_toplevel">
>        <description summary="import a toplevel surface">
>         The import_toplevel request imports a surface from any client given a handle
> -       retrieved by exporting said surface using xdg_exporter.export. When
> -       called, a new xdg_imported object will be created. This new object
> +       retrieved by exporting said surface using xdg_exporter.export_toplevel.
> +       When called, a new xdg_imported object will be created. This new object
>         represents the imported surface, and the importing client can
>         manipulate its relationship using it. See xdg_imported for details.
>        </description>
> @@ -136,8 +136,8 @@
>        <description summary="the exported surface handle">
>         The handle event contains the unique handle of this exported surface
>         reference. It may be shared with any client, which then can use it to
> -       import the surface by calling xdg_importer.import. A handle may be
> -       used to import the surface multiple times.
> +       import the surface by calling xdg_importer.import_toplevel. A handle
> +       may be used to import the surface multiple times.
>        </description>
>        <arg name="handle" type="string" summary="the exported surface handle"/>
>      </event>
> @@ -161,9 +161,9 @@
>      <request name="set_parent_of">
>        <description summary="set as the parent of some surface">
>         Set the imported surface as the parent of some surface of the client.
> -       The passed surface must be a toplevel xdg_surface. Calling this function
> -       sets up a surface to surface relation with the same stacking and positioning
> -       semantics as xdg_surface.set_parent.
> +       The passed surface must be a xdg_toplevel equivalent. Calling this
> +       function sets up a surface to surface relation with the same stacking
> +       and positioning semantics as xdg_toplevel.set_parent.
>        </description>
>        <arg name="surface" type="object" interface="wl_surface"
>            summary="the child surface"/>
> --
> 2.13.5
>
sorry i'm insisting on this.. what is still needed for those? can then
be pushed?

--
Marco Martin

On Mon, Oct 2, 2017 at 2:55 PM, Marco Martin <notmart@gmail.com> wrote:
> ping? shouldn't the 3 patches in total be pushed now?
>
> --
> Marco Martin
>
> On Tue, Sep 26, 2017 at 3:53 PM, Jonas Ådahl <jadahl@gmail.com> wrote:
>> It stilled referred to the removed requests, so change those places to
>> refer to the renamed ones.
>>
>> While at it, also change documentation to refer directly to
>> xdg_toplevel, as that has now been introduced.
>>
>> Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
>> ---
>>
>> Hi,
>>
>> On Tue, Sep 26, 2017 at 03:06:05PM +0200, Marco Martin wrote:
>>> ping?
>>>
>>
>> The API change looks good to me, but the documentation was left
>> unchanged, thus incorrect. I fixed it in this patch. Please take a look.
>>
>> Locally I did some minor commit message changes to your patches. For
>> example I changed the commit message to say 'xdg-foreign' not just
>> 'foreign', as well as some minor similar cosmetic issues.
>>
>>
>> Jonas
>>
>>
>>
>>
>>  unstable/xdg-foreign/xdg-foreign-unstable-v2.xml | 30 ++++++++++++------------
>>  1 file changed, 15 insertions(+), 15 deletions(-)
>>
>> diff --git a/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml b/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
>> index 8e824c1..bf46fa8 100644
>> --- a/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
>> +++ b/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
>> @@ -32,12 +32,12 @@
>>      some of its own surface above the other clients surface.
>>
>>      In order for a client A to get a reference of a surface of client B, client
>> -    B must first export its surface using xdg_exporter.export. Upon doing this,
>> -    client B will receive a handle (a unique string) that it may share with
>> -    client A in some way (for example D-Bus). After client A has received the
>> -    handle from client B, it may use xdg_importer.import to create a reference
>> -    to the surface client B just exported. See the corresponding requests for
>> -    details.
>> +    B must first export its surface using xdg_exporter.export_toplevel. Upon
>> +    doing this, client B will receive a handle (a unique string) that it may
>> +    share with client A in some way (for example D-Bus). After client A has
>> +    received the handle from client B, it may use xdg_importer.import_toplevel
>> +    to create a reference to the surface client B just exported. See the
>> +    corresponding requests for details.
>>
>>      A possible use case for this is out-of-process dialogs. For example when a
>>      sandboxed client without file system access needs the user to select a file
>> @@ -77,8 +77,8 @@
>>         corresponding interface and event for details.
>>
>>         A surface may be exported multiple times, and each exported handle may
>> -       be used to create a xdg_imported multiple times. Only xdg_surface
>> -       surfaces may be exported.
>> +       be used to create a xdg_imported multiple times. Only xdg_toplevel
>> +       equivalent surfaces may be exported.
>>        </description>
>>        <arg name="id" type="new_id" interface="zxdg_exported_v2"
>>            summary="the new xdg_exported object"/>
>> @@ -104,8 +104,8 @@
>>      <request name="import_toplevel">
>>        <description summary="import a toplevel surface">
>>         The import_toplevel request imports a surface from any client given a handle
>> -       retrieved by exporting said surface using xdg_exporter.export. When
>> -       called, a new xdg_imported object will be created. This new object
>> +       retrieved by exporting said surface using xdg_exporter.export_toplevel.
>> +       When called, a new xdg_imported object will be created. This new object
>>         represents the imported surface, and the importing client can
>>         manipulate its relationship using it. See xdg_imported for details.
>>        </description>
>> @@ -136,8 +136,8 @@
>>        <description summary="the exported surface handle">
>>         The handle event contains the unique handle of this exported surface
>>         reference. It may be shared with any client, which then can use it to
>> -       import the surface by calling xdg_importer.import. A handle may be
>> -       used to import the surface multiple times.
>> +       import the surface by calling xdg_importer.import_toplevel. A handle
>> +       may be used to import the surface multiple times.
>>        </description>
>>        <arg name="handle" type="string" summary="the exported surface handle"/>
>>      </event>
>> @@ -161,9 +161,9 @@
>>      <request name="set_parent_of">
>>        <description summary="set as the parent of some surface">
>>         Set the imported surface as the parent of some surface of the client.
>> -       The passed surface must be a toplevel xdg_surface. Calling this function
>> -       sets up a surface to surface relation with the same stacking and positioning
>> -       semantics as xdg_surface.set_parent.
>> +       The passed surface must be a xdg_toplevel equivalent. Calling this
>> +       function sets up a surface to surface relation with the same stacking
>> +       and positioning semantics as xdg_toplevel.set_parent.
>>        </description>
>>        <arg name="surface" type="object" interface="wl_surface"
>>            summary="the child surface"/>
>> --
>> 2.13.5
>>
Sorry again. I've been traveling for a bit more than two weeks, so time
has been extra limited recently. It's pushed now however, and 1.11 is
released.


Jonas

On Tue, Oct 10, 2017 at 01:16:09PM +0200, Marco Martin wrote:
> sorry i'm insisting on this.. what is still needed for those? can then
> be pushed?
> 
> --
> Marco Martin
> 
> On Mon, Oct 2, 2017 at 2:55 PM, Marco Martin <notmart@gmail.com> wrote:
> > ping? shouldn't the 3 patches in total be pushed now?
> >
> > --
> > Marco Martin
> >
> > On Tue, Sep 26, 2017 at 3:53 PM, Jonas Ådahl <jadahl@gmail.com> wrote:
> >> It stilled referred to the removed requests, so change those places to
> >> refer to the renamed ones.
> >>
> >> While at it, also change documentation to refer directly to
> >> xdg_toplevel, as that has now been introduced.
> >>
> >> Signed-off-by: Jonas Ådahl <jadahl@gmail.com>
> >> ---
> >>
> >> Hi,
> >>
> >> On Tue, Sep 26, 2017 at 03:06:05PM +0200, Marco Martin wrote:
> >>> ping?
> >>>
> >>
> >> The API change looks good to me, but the documentation was left
> >> unchanged, thus incorrect. I fixed it in this patch. Please take a look.
> >>
> >> Locally I did some minor commit message changes to your patches. For
> >> example I changed the commit message to say 'xdg-foreign' not just
> >> 'foreign', as well as some minor similar cosmetic issues.
> >>
> >>
> >> Jonas
> >>
> >>
> >>
> >>
> >>  unstable/xdg-foreign/xdg-foreign-unstable-v2.xml | 30 ++++++++++++------------
> >>  1 file changed, 15 insertions(+), 15 deletions(-)
> >>
> >> diff --git a/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml b/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
> >> index 8e824c1..bf46fa8 100644
> >> --- a/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
> >> +++ b/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml
> >> @@ -32,12 +32,12 @@
> >>      some of its own surface above the other clients surface.
> >>
> >>      In order for a client A to get a reference of a surface of client B, client
> >> -    B must first export its surface using xdg_exporter.export. Upon doing this,
> >> -    client B will receive a handle (a unique string) that it may share with
> >> -    client A in some way (for example D-Bus). After client A has received the
> >> -    handle from client B, it may use xdg_importer.import to create a reference
> >> -    to the surface client B just exported. See the corresponding requests for
> >> -    details.
> >> +    B must first export its surface using xdg_exporter.export_toplevel. Upon
> >> +    doing this, client B will receive a handle (a unique string) that it may
> >> +    share with client A in some way (for example D-Bus). After client A has
> >> +    received the handle from client B, it may use xdg_importer.import_toplevel
> >> +    to create a reference to the surface client B just exported. See the
> >> +    corresponding requests for details.
> >>
> >>      A possible use case for this is out-of-process dialogs. For example when a
> >>      sandboxed client without file system access needs the user to select a file
> >> @@ -77,8 +77,8 @@
> >>         corresponding interface and event for details.
> >>
> >>         A surface may be exported multiple times, and each exported handle may
> >> -       be used to create a xdg_imported multiple times. Only xdg_surface
> >> -       surfaces may be exported.
> >> +       be used to create a xdg_imported multiple times. Only xdg_toplevel
> >> +       equivalent surfaces may be exported.
> >>        </description>
> >>        <arg name="id" type="new_id" interface="zxdg_exported_v2"
> >>            summary="the new xdg_exported object"/>
> >> @@ -104,8 +104,8 @@
> >>      <request name="import_toplevel">
> >>        <description summary="import a toplevel surface">
> >>         The import_toplevel request imports a surface from any client given a handle
> >> -       retrieved by exporting said surface using xdg_exporter.export. When
> >> -       called, a new xdg_imported object will be created. This new object
> >> +       retrieved by exporting said surface using xdg_exporter.export_toplevel.
> >> +       When called, a new xdg_imported object will be created. This new object
> >>         represents the imported surface, and the importing client can
> >>         manipulate its relationship using it. See xdg_imported for details.
> >>        </description>
> >> @@ -136,8 +136,8 @@
> >>        <description summary="the exported surface handle">
> >>         The handle event contains the unique handle of this exported surface
> >>         reference. It may be shared with any client, which then can use it to
> >> -       import the surface by calling xdg_importer.import. A handle may be
> >> -       used to import the surface multiple times.
> >> +       import the surface by calling xdg_importer.import_toplevel. A handle
> >> +       may be used to import the surface multiple times.
> >>        </description>
> >>        <arg name="handle" type="string" summary="the exported surface handle"/>
> >>      </event>
> >> @@ -161,9 +161,9 @@
> >>      <request name="set_parent_of">
> >>        <description summary="set as the parent of some surface">
> >>         Set the imported surface as the parent of some surface of the client.
> >> -       The passed surface must be a toplevel xdg_surface. Calling this function
> >> -       sets up a surface to surface relation with the same stacking and positioning
> >> -       semantics as xdg_surface.set_parent.
> >> +       The passed surface must be a xdg_toplevel equivalent. Calling this
> >> +       function sets up a surface to surface relation with the same stacking
> >> +       and positioning semantics as xdg_toplevel.set_parent.
> >>        </description>
> >>        <arg name="surface" type="object" interface="wl_surface"
> >>            summary="the child surface"/>
> >> --
> >> 2.13.5
> >>