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 <[email protected]> --- doc/doxygen/Makefile.am | 71 ++++++++++++++++++++++++++++++++++++++++-- doc/doxygen/wayland.doxygen.in | 6 ++-- protocol/wayland.xml | 2 +- 3 files changed, 73 insertions(+), 6 deletions(-) diff --git a/doc/doxygen/Makefile.am b/doc/doxygen/Makefile.am index fdbb246..40dcecb 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 12d0817..e700e3d 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. diff --git a/protocol/wayland.xml b/protocol/wayland.xml index 9a0aa15..436d5b4 100644 --- a/protocol/wayland.xml +++ b/protocol/wayland.xml @@ -57,7 +57,7 @@ The error event is sent out when a fatal (non-recoverable) error has occurred. The @object_id argument is the object where the error occurred, most often in response to a request - to that object. The @code identifies the error and is defined + to that object. The code identifies the error and is defined by the object interface. As such, each interface defines its own set of error codes. The @message is an brief description of the error, for (debugging) convenience. -- 1.8.1.4 _______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
