[PATCH] Documentation for the prepare_lock_surface event description, is incorrect

[Pekka Paalanen]

On Thu, 9 Jul 2015 13:46:46 -0400
Christopher Michael <cpmichael at osg.samsung.com> wrote:

> Here is an updated patch which changes the wording to match what Giulio 
> offered.
> 
> Documentation for the prepare_lock_surface event description is
> incorrect. The summary says "Tell the client..." however the full-text
> description says "tell the shell..."
> 
> Signed-off-by: Chris Michael <cp.michael at samsung.com>
> ---
>   protocol/desktop-shell.xml | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/protocol/desktop-shell.xml b/protocol/desktop-shell.xml
> index fb0b748..6ec9dfa 100644
> --- a/protocol/desktop-shell.xml
> +++ b/protocol/desktop-shell.xml
> @@ -44,7 +44,7 @@
> 
>       <event name="prepare_lock_surface">
>         <description summary="tell the client to create, set the lock 
> surface">
> -	Tell the shell we want it to create and set the lock surface, which is
> +	Tell the client we want it to create and set the lock surface, which is
>   	a GUI asking the user to unlock the screen. The lock surface is
>   	announced with 'set_lock_surface'. Whether or not the shell actually
>   	implements locking, it MUST send 'unlock' request to let the normal

Acked-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
but I think you could do even better.

There's another "shell" in the context here that also refers to the client.

To be exact, shells currently in Weston have two parts: the plugin, and
the helper client. The shell helper client is a privileged client that
alone has access to the desktop-shell.xml protocol.

"We" in the above excerpt seems to refer to the compositor or the shell
plugin specifically. I have found using such pronouns in spec language
to be confusing, as it is not always obvious who "you" or "we" are.

Maybe this helps you to revise and clarify the whole desktop-shell.xml
wording?

However, using the term "plugin" in protocol spec language is not
really good either, because the shell's compositor side implementation
may not be a plugin. Libweston is heading this way, eventually
eliminating shells as plugins and turning them into main executables.

So, we have the shell helper client and the shell implementation in the
compositor. I don't have good short terms to suggest for these two
concepts.


Thanks,
pq