On Fri, Feb 26, 2016 at 05:00:15PM +0200, Pekka Paalanen wrote: > 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?
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) _______________________________________________ wayland-devel mailing list [email protected] https://lists.freedesktop.org/mailman/listinfo/wayland-devel
