From 8ccab1ba621c299b8cedbc6ac1c673967febf316 Mon Sep 17 00:00:00 2001 From: Peter Hutterer Date: Tue, 2 Apr 2013 11:08:59 +1000 Subject: [PATCH] doc: generate man pages from doxygen Create client-side and server-side man pages from doxygen. The doxygen config options are virtually the same as for the XML output, but we do pass in the specific options via stdin. WL_EXPORT is predefined to the empty string, it makes the man page look confusing and provides no value here anyway. This applies for both xml and man output. JAVADOC_AUTOBRIEF is disabled for man pages, the formatting in the resulting man page is IMO hard to read. Most of the server man pages are virtually empty, there's just not enough documentation in the source files. Interesting issue: the usage of @code in the protocol to reference the parameter breaks the expansion of WL_EXPORT, thus leaving us with WL_EXPORT in all the man pages. Presumably this is an issue with doxygen interpreting this as a @code command, but I already wasted enough time narrowing this down. Signed-off-by: Peter Hutterer --- doc/doxygen/Makefile.am | 71 +++++++++++++++++++++++++++++++++- doc/doxygen/wayland.doxygen.in | 6 +-- 2 files changed, 72 insertions(+), 5 deletions(-) diff --git a/doc/doxygen/Makefile.am b/doc/doxygen/Makefile.am index fdbb2465..40dcecbe 100644 --- a/doc/doxygen/Makefile.am +++ b/doc/doxygen/Makefile.am @@ -2,12 +2,79 @@ noinst_DATA = xml/index.xml dist_noinst_DATA = wayland.doxygen.in -scanned_src_files = \ +scanned_src_files_client = \ $(top_srcdir)/src/wayland-client.c \ $(top_srcdir)/src/wayland-client.h -xml/index.xml: $(scanned_src_files) wayland.doxygen +scanned_src_files_server = \ + $(top_srcdir)/src/wayland-server.c \ + $(top_srcdir)/src/wayland-server.h + +client_MANPAGES = \ + man/man3/wl_display.3 \ + man/man3/wl_display_connect.3 \ + man/man3/wl_display_connect_to_fd.3 \ + man/man3/wl_display_create_queue.3 \ + man/man3/wl_display_disconnect.3 \ + man/man3/wl_display_dispatch.3 \ + man/man3/wl_display_dispatch_pending.3 \ + man/man3/wl_display_dispatch_queue.3 \ + man/man3/wl_display_dispatch_queue_pending.3 \ + man/man3/wl_display_flush.3 \ + man/man3/wl_display_get_error.3 \ + man/man3/wl_display_get_fd.3 \ + man/man3/wl_display_roundtrip.3 \ + man/man3/wl_event_queue.3 \ + man/man3/wl_event_queue_destroy.3 \ + man/man3/wl_proxy.3 \ + man/man3/wl_proxy_add_listener.3 \ + man/man3/wl_proxy_create.3 \ + man/man3/wl_proxy_destroy.3 \ + man/man3/wl_proxy_get_class.3 \ + man/man3/wl_proxy_get_id.3 \ + man/man3/wl_proxy_get_user_data.3 \ + man/man3/wl_proxy_marshal.3 \ + man/man3/wl_proxy_set_queue.3 \ + man/man3/wl_proxy_set_user_data.3 + +server_MANPAGES = \ + man/man3/wl_buffer.3 \ + man/man3/wl_client.3 \ + man/man3/wl_data_offer.3 \ + man/man3/wl_data_source.3 \ + man/man3/wl_global.3 \ + man/man3/wl_keyboard.3 \ + man/man3/wl_keyboard_grab.3 \ + man/man3/wl_keyboard_grab_interface.3 \ + man/man3/wl_listener.3 \ + man/man3/wl_pointer.3 \ + man/man3/wl_pointer_grab.3 \ + man/man3/wl_pointer_grab_interface.3 \ + man/man3/wl_resource.3 \ + man/man3/wl_seat.3 \ + man/man3/wl_signal.3 \ + man/man3/wl_socket.3 \ + man/man3/wl_surface.3 \ + man/man3/wl_touch.3 \ + man/man3/wl_touch_grab.3 \ + man/man3/wl_touch_grab_interface.3 + +man3_MANS= $(client_MANPAGES) $(server_MANPAGES) + +xml/index.xml: $(scanned_src_files_client) wayland.doxygen doxygen wayland.doxygen +doxygen.man: $(scanned_src_files_client) $(scanned_src_files_server) + (cat wayland.doxygen; \ + echo "GENERATE_XML=NO"; \ + echo "GENERATE_MAN=YES"; \ + echo "MAN_OUTPUT=man"; \ + echo "JAVADOC_AUTOBRIEF=NO"; \ + echo "INPUT= $^"; \ + ) | doxygen - + +$(client_MANPAGES) $(server_MANPAGES): doxygen.man + clean-local: rm -rf xml/ + rm -rf man/ diff --git a/doc/doxygen/wayland.doxygen.in b/doc/doxygen/wayland.doxygen.in index 12d0817f..e700e3db 100644 --- a/doc/doxygen/wayland.doxygen.in +++ b/doc/doxygen/wayland.doxygen.in @@ -1453,13 +1453,13 @@ ENABLE_PREPROCESSING = YES # compilation will be performed. Macro expansion can be done in a controlled # way by setting EXPAND_ONLY_PREDEF to YES. -MACRO_EXPANSION = NO +MACRO_EXPANSION = YES # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES # then the macro expansion is limited to the macros specified with the # PREDEFINED and EXPAND_AS_DEFINED tags. -EXPAND_ONLY_PREDEF = NO +EXPAND_ONLY_PREDEF = YES # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # pointed to by INCLUDE_PATH will be searched when a #include is found. @@ -1487,7 +1487,7 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = +PREDEFINED = WL_EXPORT= # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded.