[PATCH wayland-protocols] xdg_shell: add missing <description> tags to the 'state' enum entries

[Peter Hutterer]

On Mon, Nov 09, 2015 at 11:14:32AM -0600, Derek Foreman wrote:
> On 08/11/15 09:58 PM, Peter Hutterer wrote:
> > The scanner parses CDATA in <entry> but lets it disappear otherwise. To have
> > descriptive text associated with the <entry>, we need a <description> tag -
> > and that must have a summary attribute. The current scanner doesn't handle
> > <description> however, so to get the summary printed in the output file we
> > still need the summary attribute in the entry tag too.
> 
> Kinda gross.  wayland.xml seems to get this wrong all over the place?
> (wrt missing summary= in some sections)
> 
> Should we be teaching the scanner about <description> to avoid the need
> for duplication?

Once we merge the doxygen patches, the description tag will be used
properly and we can drop the summary attribute from the <entry> tag (that
may require an extra patch, I'll check). that way we can either have a
summary attribute in <entry> or, instead, a <description summary="">. I
think that's a good middle-ground, most entries don't need more than a
summary. The duplication is just for the current scanner.

> > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
> 
> Reviewed-by: Derek Foreman <derekf at osg.samsung.com>

thanks

Cheers,
   Peter

> > ---
> >  unstable/xdg-shell/xdg-shell-unstable-v5.xml | 34 +++++++++++++++++-----------
> >  1 file changed, 21 insertions(+), 13 deletions(-)
> > 
> > diff --git a/unstable/xdg-shell/xdg-shell-unstable-v5.xml b/unstable/xdg-shell/xdg-shell-unstable-v5.xml
> > index 64346fb..127992b 100644
> > --- a/unstable/xdg-shell/xdg-shell-unstable-v5.xml
> > +++ b/unstable/xdg-shell/xdg-shell-unstable-v5.xml
> > @@ -340,23 +340,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 summary="the surface is maximized">
> > +	  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 summary="the surface is fullscreen">
> > +	  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.
> > +      <entry name="resizing" value="3" summary="the surface is being resized">
> > +	<description summary="the surface is being resized">
> > +	  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.
> > +      <entry name="activated" value="4" summary="the surface is now activated">
> > +	<description summary="the surface is now activated">
> > +	  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>
> >  
> > 
>