[PATCH RFC] doc: coerce doxygen into grouping man pages more sensibly
Kristian Høgsberg
hoegsberg at gmail.com
Thu Apr 4 13:56:53 PDT 2013
On Thu, Apr 04, 2013 at 11:18:33AM +1000, Peter Hutterer wrote:
> 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.
I wouldn't worry about the server side API too much for now, except
for the core IPC functions (wl_display_* and wl_proxy_*). One of the
ideas for post 1.1 is to move most of the input helpers and structs
out of libwayland-server and into weston and then leave
libwayland-server as just the IPC code. What we have now is a bunch
of big structs, very little shared code and a lot of undocumented
assumptions about how those structs should work together.
The goal was to be able to share much of the input layer logic and the
data device code (dnd and selection) between compositors, but what we
have now is 500 lines of input code in wayland-server.c (lines
474-986) and 500 lines in data-device.c, along with 200 lines of input
structs in wayland-server. In other words, it's a disaster.
If anything, the lesson is that it's very hard to abstract out the
input layer code in a meaningful way, without also sharing the
scenegraph code.
Kristian
> 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
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list