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

Mon Feb 29 07:08:29 UTC 2016

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>

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

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

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

Cheers,
  Peter

> 
> > ---
> > Changes to v3:
> > - rebased onto cde251a124d
> > 
> >  doc/doxygen/Makefile.am        |  27 +++++-
> >  doc/doxygen/mainpage.dox       |  13 +++
> >  doc/doxygen/wayland.doxygen.in |   5 +-
> >  src/scanner.c                  | 214 ++++++++++++++++++++++++++---------------
> >  4 files changed, 180 insertions(+), 79 deletions(-)
> >  create mode 100644 doc/doxygen/mainpage.dox
> > 
> > diff --git a/doc/doxygen/Makefile.am b/doc/doxygen/Makefile.am
> > index a8bb95f..e80c401 100644
> > --- a/doc/doxygen/Makefile.am
> > +++ b/doc/doxygen/Makefile.am
> > @@ -1,7 +1,11 @@
> >  
> >  .SUFFIXES = .gv .png .map
> >  
> > -noinst_DATA = xml/Client/index.xml xml/Server/index.xml
> > +noinst_DATA = \
> > +              xml/Client/index.xml \
> > +              xml/Server/index.xml \
> > +              html/Client/index.html \
> > +              html/Server/index.html
> >  dist_noinst_DATA = wayland.doxygen.in
> >  
> >  scanned_src_files_shared = 				\
> > @@ -27,6 +31,17 @@ scanned_src_files_man =					\
> >  	$(top_srcdir)/src/wayland-client.h	\
> >  	$(top_srcdir)/src/wayland-client-core.h
> >  
> > +extra_doxygen = \
> > +	mainpage.dox
> > +
> > +extra_doxygen_Server = \
> > +	$(top_builddir)/protocol/wayland-server-protocol.h \
> > +	$(extra_doxygen)
> > +
> > +extra_doxygen_Client = \
> > +	$(top_builddir)/protocol/wayland-client-protocol.h \
> > +	$(extra_doxygen)
> > +
> >  diagramsdir := $(srcdir)/dot
> >  diagramssrc := $(wildcard $(diagramsdir)/*.gv)
> >  diagrams := $(patsubst $(diagramsdir)/%,xml/%,$(diagramssrc:.gv=.png))
> > @@ -38,7 +53,7 @@ diagram_maps := $(patsubst $(diagramsdir)/%,xml/%,$(diagramssrc:.gv=.map))
> >  dist_man3_MANS = $(shell test -d man && find man/man3 -name "wl_*.3" -printf "man/man3/%P\n")
> >  
> >  # Listing various directories that might need to be created.
> > -alldirs := xml xml/Client xml/Server man/man3
> > +alldirs := xml xml/Client xml/Server man/man3 html/Client html/Server
> >  
> >  $(diagrams): $(diagramssrc)
> >  
> > @@ -51,6 +66,13 @@ xml/%/index.xml: $(top_srcdir)/src/scanner.c $(scanned_src_files_%) wayland.doxy
> >            echo "INPUT= $(scanned_src_files_$*)"; \
> >            ) | $(DOXYGEN) -
> >  
> > +html/%/index.html: $(scanned_src_files_%) wayland.doxygen $(diagrams) $(diagram_maps) | html/%
> > +	$(AM_V_GEN)(cat wayland.doxygen; \
> > +          echo "GENERATE_HTML=YES"; \
> > +          echo "HTML_OUTPUT=html/$*"; \
> > +          echo "INPUT= $(scanned_src_files_$*) $(extra_doxygen_$*)"; \
> > +          ) | $(DOXYGEN) -
> > +
> >  man/man3/wl_display.3: $(top_srcdir)/src/scanner.c $(scanned_src_files_man) wayland.doxygen | man/man3
> >  	$(AM_V_GEN)(cat wayland.doxygen; \
> >            echo "GENERATE_MAN=YES"; \
> > @@ -74,6 +96,7 @@ all-local: man/man3/wl_display.3
> >  
> >  clean-local:
> >  	rm -rf xml/
> > +	rm -rf html/
> >  	rm -rf man/
> >  
> >  EXTRA_DIST = $(diagramssrc)