On Fri, 30 May 2014 11:52:29 +0200 Jonny Lamb <[email protected]> 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 _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
