[PATCH v3 wayland 3/3] doc: generate doxygen html output from the scanner

[Peter Hutterer]

On Mon, Feb 29, 2016 at 03:41:39PM +0200, Pekka Paalanen wrote:
> On Mon, 29 Feb 2016 17:08:29 +1000
> Peter Hutterer <peter.hutterer at who-t.net> wrote:
> 
> > On Fri, Feb 26, 2016 at 05:00:15PM +0200, Pekka Paalanen wrote:
> > > On Mon, 22 Feb 2016 08:57:47 +1000
> > > Peter Hutterer <peter.hutterer at who-t.net> wrote:
> > >   
> > > > This switches the scanner to generate doxygen-compatible tags for the
> > > > generated protocol headers, and hooks up the doxygen build to generate server
> > > > and client-side API documentation.
> > > > 
> > > > Each protocol is a separate doxygen @page, with each interface a @subpage.
> > > > Wayland only has one protocol, wayland-protocols will have these nested.
> > > > Each protocol page has a list of interfaces and the copyright and description
> > > > where available.
> > > > All interfaces are grouped by doxygen @defgroup and @ingroups and appear in
> > > > "Modules" in the generated output. Each interface subpage has the description
> > > > and a link to the actual API doc.
> > > > Function, struct and #defines are documented in doxygen style and associated
> > > > with the matching interface.
> > > > 
> > > > Note that pages and groups have fixed HTML file names and are directly
> > > > linkable/bookmark-able.
> > > > 
> > > > The @mainpage is a separate file that's included at build time. It doesn't
> > > > contain much other than links to where the interesting bits are. It's a static
> > > > file though that supports markdown, so we can extend it easily in the future.
> > > > 
> > > > For doxygen we need the new options EXTRACT_ALL and OPTIMIZE_OUTPUT_FOR_C so
> > > > it scans C code properly. EXTRACT_STATIC is needed since most of the protocol
> > > > hooks are static. WARN_IF_DOC_ERROR is required to silence the warnings when
> > > > some parameters are documented but others aren't.
> > > > 
> > > > Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>  
> > > 
> > > Hi Peter,
> > > 
> > > I started looking at the output of this, and it took a while to realize
> > > where all the output goes. Nothing much changes with the existing
> > > documentation we install, so I got puzzled.
> > > 
> > > Then I looked at doc/doxygen/html/index.html and it didn't seem to have
> > > what you described.
> > > 
> > > Then re-reading the Makefile.am and which directory it is in, I
> > > realized I need to look at doc/doxygen/html/Client/index.html and
> > > doc/doxygen/html/Server/index.html. These are the main outputs of this
> > > patch, right?  
> > 
> > yes, sorry, i should've pointed this out in the commit message.
> >  
> > > I get the feeling the generated documentation is quite scattered and
> > > not easy to find, but you probably intend to fix that in future?
> > > I have quite forgot the earlier discussions, sorry.  
> > 
> > I'm not quite sure what you mean here. the documentation is in normal
> > doxygen format, all protocol interfaces are on the related page but also in
> > the modules. One drawback is that each interface page is little more than a
> > stop through to the module page but I don't know how to fix this within
> > doxygen. That's a bit of a roundabout way but it makes more sense for
> > wayland-protocols where we have more than one <protocol>
> 
> Hi Peter,
> 
> that was more about that you need to know to go to:
> - doc/doxygen/html/index.html for libwayland API docs

These shouldn't be generated anymore, turns out this was a bug with the
makefile/doxygen. GENERATE_HTML is on by default so unless we turn it off,
the xml and man page targets produce that output. I've fixed that in the
v4.

> - doc/doxygen/html/Client/index.html for client protocol API docs
> - doc/doxygen/html/Server/index.html for server protocol API docs
> - and then the "Wayland book" that gets installed is yet another
>   independent entity
> 
> None of these contain links to the other that I could see, they are all
> completely independent, and mostly not installed.
> 
> Even a top-level page that just contained links to these "books" would
> go a long way.
> 
> That's all fine to sort out later.

Patch in mid-flight, I kept this one separate though.

> > > Looking at e.g.
> > > file:///home/pq/git/wayland/doc/doxygen/html/Client/group__iface__wl__surface.html
> > > it seems all the function documentations are missing. Well, they were
> > > missing also before.  
> > 
> > weird. This should be part of the output but it somehow got lost. New
> > patch coming up that reinstates this.
> 
> Nice.
> 
> > > I have opposed silencing the warnings about undocumented parameters
> > > before. Is there something here that makes documenting all parameters
> > > not possible, rather than just not having written docs in XML?  
> > 
> > I've added @param resource_ where we do so, the rest would need to be in the
> > xml. The other option would be to add a fake documentation, so you get
> > something like
> >    @param foo Undocumented parameter foo
> > or similar. Not a fan of this though, better to document it in the protocol.
> 
> Right, it would be good if the scanner fills in all the parameters you
> cannot document in the xml, and rely on the xml for the rest. Things
> like wl_registry.bind's C API have several arguments for a single XML
> <arg>.
> 
> IMHO, undocumented parameters should cause noise and not be silenced by
> stub docs.

I *think* at this point all leftover warnings are for things that could be
documented in the xml file.
 
> > > When I compare old and new wayland-client-protocol.h, I see that in the
> > > beginning with the list of extern const struct wl_interface
> > > wl_display_interface; etc. the documentation seems to be twice in the
> > > new comment. Is that necessary?  
> > 
> > Basically yes. the output is:
> > 
> > /**
> >  * @page page_iface_wl_display wl_display
> >  * @section page_iface_wl_display_desc Description
> >  *
> >  * The core global object.  This is a special singleton object.  It
> >  * is used for internal Wayland protocol features.
> >  * @section page_iface_wl_display_api API
> >  * See @ref iface_wl_display.
> >  *
> >  * @defgroup iface_wl_display The wl_display interface
> >  *
> >  * The core global object.  This is a special singleton object.
> >  * It is used for internal Wayland protocol features.
> >  */
> > 
> > Note the @page and @defgroup command. The first defines a page (see Related
> > Pages which then links to the module), the second defines a group that we can
> > then group the various commands in. It is trivial to separate
> > those two into two comment blocks to make it easier to recognise. I've done
> > this in the new patch.
> 
> Ok. What was the purpose to have a @page in addition to the group?

this is the bit that makes more sense for wayland-protocols. modules are
flat, pages have a two-level hierarchy (page and subpage). In core wayland
we only have one page, in w-p we have one per protocol with the interfaces
being subpages. So the Related Pages gives us a tree:
https://people.freedesktop.org/~whot/wayland-doxygen/wayland-protocols/Client/pages.html
(this is an older version of w-p, but still looks the same)

Cheers,
   Peter