On Mon, 22 Feb 2016 08:57:47 +1000 Peter Hutterer <[email protected]> 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 <[email protected]> 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)
pgp9BOJDyaZMc.pgp
Description: OpenPGP digital signature
_______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
