[PATCH weston] xdg-shell: add description tags where missing

[Pekka Paalanen]

On Fri, 30 May 2014 11:52:29 +0200
Jonny Lamb <jonny.lamb at collabora.co.uk> wrote:

> wayland.dtd specifies the use of the description tags inside entry so
> let's use them.
> ---
>  protocol/xdg-shell.xml | 30 +++++++++++++++++++-----------
>  1 file changed, 19 insertions(+), 11 deletions(-)
> 
> diff --git a/protocol/xdg-shell.xml b/protocol/xdg-shell.xml
> index 28add40..00ff39f 100644
> --- a/protocol/xdg-shell.xml
> +++ b/protocol/xdg-shell.xml
> @@ -283,23 +283,31 @@
>          0x1000 - 0x1FFF: GNOME
>        </description>
>        <entry name="maximized" value="1" summary="the surface is maximized">
> -        The surface is maximized. The window geometry specified in the configure
> -        event must be obeyed by the client.
> +        <description>
> +          The surface is maximized. The window geometry specified in the configure
> +          event must be obeyed by the client.
> +        </description>
>        </entry>
>        <entry name="fullscreen" value="2" summary="the surface is fullscreen">
> -        The surface is fullscreen. The window geometry specified in the configure
> -        event must be obeyed by the client.
> +        <description>
> +          The surface is fullscreen. The window geometry specified in the configure
> +          event must be obeyed by the client.
> +        </description>
>        </entry>
>        <entry name="resizing" value="3">
> -        The surface is being resized. The window geometry specified in the
> -        configure event is a maximum; the client cannot resize beyond it.
> -        Clients that have aspect ratio or cell sizing configuration can use
> -        a smaller size, however.
> +        <description>
> +          The surface is being resized. The window geometry specified in the
> +          configure event is a maximum; the client cannot resize beyond it.
> +          Clients that have aspect ratio or cell sizing configuration can use
> +          a smaller size, however.
> +        </description>
>        </entry>
>        <entry name="activated" value="4">
> -        Client window decorations should be painted as if the window is
> -        active. Do not assume this means that the window actually has
> -        keyboard or pointer focus.
> +        <description>
> +          Client window decorations should be painted as if the window is
> +          active. Do not assume this means that the window actually has
> +          keyboard or pointer focus.
> +        </description>
>        </entry>
>      </enum>
>  

Does the Wayland documentation generator parse and use these? I can't
test, because I still don't have publican.

I think wayland-scanner at least simply ignores these, as I tried to
use a similar pattern, and I even got wayland-scanner to generate
broken documentation (wrong comment picked for a thing). Element
"entry" can have attribute "summary" which is picked up, but element
description also can have "summary", so we'd have two conflicting
summaries allowed in the DTD. If you mix entry-summary with entries
without summary but with description, you get wrong docs.

Here I think the DTD is just not describing what's actually working.

I would really like to have "description" element or the contents-as-doc
working for enum entries, since I have some documentation that is
simply too long as a summary.

Since "arg" already has "summary" attribute, could we just make the
<arg> contents as long documentation -feature work?

Suggestions, anyone?


Thanks,
pq