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

Mon Feb 29 13:41:39 UTC 2016

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
- 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.

> > 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.

> > 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?

Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 811 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20160229/a228c11a/attachment.sig>