The \file comment at the top is required to tell doxygen that this file actually has members (or use EXTRACT_ALL, which in our setup has the same effect since we restrict the source files)
By default, all function's man pages end up as links to wayland-server.h.3, all structs have their own man page. By adding grouping, together with INLINE_GROUPED_CLASSES=yes, we can coerce doxygen into creating a single man page (wl_keyboard.3 in this case) that contains the structs and functions in that group, with the respective man pages now all pointing to that one man page. Signed-off-by: Peter Hutterer <[email protected]> --- This is an example of how to make the doxygen man pages more useful. Right now, the man pages (especially server-side) are mostly for the structs and contain virtually no information since nothing is documented. Functions aren't extracted and even with the EXTRACT_ALL/@file command they all just link into wayland-server.h.3 grouping is the solution here, it's still not as nice as hand-written ones, but at least becoming usable now. The grouping needs to be maintained manually, though that's a manageable task once the initial work is done. I've attached the result file for wl_keyboard.3 as well if you want to check. Really though, what's needed here is a decision of whether the man pages will be completely manually maintained or through doxygen. I think we're hitting the limits on doxygen man page generation here and once more verbose documentation is added to the source files, they will likely be very hard to read. After fighting doxygen for too long, I'm somewhat inclined to go down the manual path, maybe through asciidoc. Cheers, Peter doc/doxygen/Makefile.am | 1 + src/wayland-server.h | 60 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) diff --git a/doc/doxygen/Makefile.am b/doc/doxygen/Makefile.am index ec43519..ea713c2 100644 --- a/doc/doxygen/Makefile.am +++ b/doc/doxygen/Makefile.am @@ -35,6 +35,7 @@ doxygen.man: $(scanned_src_files_client) $(scanned_src_files_server) echo "GENERATE_MAN=YES"; \ echo "MAN_OUTPUT=man"; \ echo "JAVADOC_AUTOBRIEF=NO"; \ + echo "INLINE_GROUPED_CLASSES=YES"; \ echo "INPUT= $^"; \ ) | doxygen - diff --git a/src/wayland-server.h b/src/wayland-server.h index af2be62..a939081 100644 --- a/src/wayland-server.h +++ b/src/wayland-server.h @@ -23,6 +23,11 @@ #ifndef WAYLAND_H #define WAYLAND_H +/** + * \file wayland-server.h + * libwayland-server public API + */ + #ifdef __cplusplus extern "C" { #endif @@ -238,6 +243,12 @@ struct wl_pointer_grab { }; struct wl_keyboard_grab; +/** + * \ingroup wl_keyboard + * + * Keyboard grab interface responsible for event handling. A default grab + * interface is provided. + */ struct wl_keyboard_grab_interface { void (*key)(struct wl_keyboard_grab *grab, uint32_t time, uint32_t key, uint32_t state); @@ -246,6 +257,11 @@ struct wl_keyboard_grab_interface { uint32_t mods_locked, uint32_t group); }; +/** + * \ingroup wl_keyboard + * + * Contains information for a keyboard grab. + */ struct wl_keyboard_grab { const struct wl_keyboard_grab_interface *interface; struct wl_keyboard *keyboard; @@ -318,6 +334,14 @@ struct wl_pointer { uint32_t button_count; }; +/** + * \defgroup wl_keyboard Wayland keyboard interface + * \brief Compositor interface to interact with the keyboard of a wl_seat. + * + */ +/** + * \ingroup wl_keyboard + */ struct wl_keyboard { struct wl_seat *seat; @@ -454,15 +478,51 @@ wl_pointer_end_grab(struct wl_pointer *pointer); void wl_pointer_set_current(struct wl_pointer *pointer, struct wl_surface *surface); +/** + * \ingroup wl_keyboard + * Initialize a keyboard to its default values. + * + * \param keyboard Pre-allocated keyboard struct to be initialized + */ void wl_keyboard_init(struct wl_keyboard *keyboard); +/** + * \ingroup wl_keyboard + * Release memory associated with the keyboard and finalize. The memory + * pointed to by keyboard will not be released. + * + * \param keyboard The keyboard to finalize. + */ void wl_keyboard_release(struct wl_keyboard *keyboard); +/** + * \ingroup wl_keyboard + * Set the focus of the keyboard to the given surface and notify clients + * that the keyboard has left the previous surface and entered the new one. + * + * \param keyboard The keyboard that just changed focus + */ void wl_keyboard_set_focus(struct wl_keyboard *keyboard, struct wl_surface *surface); +/** + * \ingroup wl_keyboard + * + * Start a grab on the given keyboard with the given grab struct. Further + * event handling will be handled by the new grab structure. + * + * \param keyboard The keyboard now grabbed + * \param grab The grab interface responsible for event handling + */ void wl_keyboard_start_grab(struct wl_keyboard *device, struct wl_keyboard_grab *grab); +/** + * \ingroup wl_keyboard + * + * End the current grab and reset to the default event handling interface. + * + * \param keyboard The keybord that just finished a grab + */ void wl_keyboard_end_grab(struct wl_keyboard *keyboard); -- 1.8.1.4
wl_keyboard.3
Description: Unix manual page
_______________________________________________ wayland-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/wayland-devel
