[PATCH RFC] doc: coerce doxygen into grouping man pages more sensibly

[Peter Hutterer]

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 <peter.hutterer at who-t.net>
---
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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: wl_keyboard.3
Type: application/x-troff-man
Size: 4565 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20130404/29913748/attachment-0001.man>