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

[Pekka Paalanen]

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?

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.

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.

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?

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?


Thanks,
pq

> ---
> 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)
-------------- 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/20160226/39291385/attachment.sig>