[PATCH v3 wayland 3/3] doc: generate doxygen html output from the scanner
ppaalanen at gmail.com
Fri Feb 26 15:00:15 UTC 2016
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
> 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>
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
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.
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?
> 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 \
> +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
> rm -rf xml/
> + rm -rf html/
> rm -rf man/
> EXTRA_DIST = $(diagramssrc)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 811 bytes
Desc: OpenPGP digital signature
More information about the wayland-devel