[PATCH wayland 4/5] man: Add man pages for event dispatch client functions

[Tiago Vignatti]

We have every entry-point documented on the code now, using doxygen 
style, with all classes referenced and so on. So, something we discussed 
before was to automate most of the man-page contents based on the 
doxygen output. I mean, this patch is nice, but have you thought about 
automating the man-page instead?

On 12/01/2012 02:33 PM, Jonas Ådahl wrote:
> Signed-off-by: Jonas Ådahl <jadahl at gmail.com>
> ---
>   doc/man/Makefile.am             |   12 +++-
>   doc/man/wl_display_dispatch.xml |  128 +++++++++++++++++++++++++++++++++++++++
>   2 files changed, 138 insertions(+), 2 deletions(-)
>   create mode 100644 doc/man/wl_display_dispatch.xml
>
> diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
> index 1c02973..5093bd9 100644
> --- a/doc/man/Makefile.am
> +++ b/doc/man/Makefile.am
> @@ -5,9 +5,14 @@
>   #
>
>   MANPAGES = \
> -	wl_display_connect.3
> +	wl_display_connect.3 \
> +	wl_display_dispatch.3
> +
>   MANPAGES_ALIASES = \
> -	wl_display_connect_to_fd.3
> +	wl_display_connect_to_fd.3 \
> +	wl_display_dispatch_pending.3 \
> +	wl_display_dispatch_queue.3 \
> +	wl_display_dispatch_queue_pending.3
>
>   XML_FILES = \
>   	${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubst %.7,%.xml,$(MANPAGES)}}}}
> @@ -50,6 +55,9 @@ fixup_aliases:
>   	$(XSLTPROC_PROCESS_MAN)
>
>   wl_display_connect_to_fd.3: wl_display_connect.3
> +wl_display_dispatch_pending.3: wl_display_dispatch.3
> +wl_display_dispatch_queue.3: wl_display_dispatch.3
> +wl_display_dispatch_queue_pending.3: wl_display_dispatch.3
>
>   endif # HAVE_MANPAGES_STYLESHEET
>   endif # HAVE_XSLTPROC
> diff --git a/doc/man/wl_display_dispatch.xml b/doc/man/wl_display_dispatch.xml
> new file mode 100644
> index 0000000..a72ae1d
> --- /dev/null
> +++ b/doc/man/wl_display_dispatch.xml
> @@ -0,0 +1,128 @@
> +<?xml version='1.0'?>
> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
> +          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
> +
> +<refentry id="wl_display_dispatch">
> +  <refentryinfo>
> +    <title>wl_display_dispatch</title>
> +    <productname>wayland-client</productname>
> +    <date>December 2012</date>
> +    <authorgroup>
> +      <author>
> +        <contrib>Developer</contrib>
> +        <firstname>Jonas</firstname>
> +        <surname>Ådahl</surname>
> +        <email>jadahl at gmail.com</email>
> +      </author>
> +    </authorgroup>
> +  </refentryinfo>
> +
> +  <refmeta>
> +    <refentrytitle>wl_display_dispatch</refentrytitle>
> +    <manvolnum>3</manvolnum>
> +  </refmeta>
> +
> +  <refnamediv>
> +    <refname>wl_display_dispatch</refname>
> +    <refname>wl_display_dispatch_pending</refname>
> +    <refname>wl_display_dispatch_queue</refname>
> +    <refname>wl_display_dispatch_queue_pending</refname>
> +    <refpurpose>queue and dispatch events</refpurpose>
> +  </refnamediv>
> +
> +  <refsynopsisdiv>
> +    <funcsynopsis>
> +
> +      <funcsynopsisinfo>#include <wayland-client.h></funcsynopsisinfo>
> +
> +      <funcprototype>
> +        <funcdef>int <function>wl_display_dispatch</function></funcdef>
> +        <paramdef>struct wl_display *<parameter>display</parameter></paramdef>
> +      </funcprototype>
> +
> +      <funcprototype>
> +        <funcdef>int <function>wl_display_dispatch_pending</function></funcdef>
> +        <paramdef>struct wl_display *<parameter>display</parameter></paramdef>
> +      </funcprototype>
> +
> +      <funcprototype>
> +        <funcdef>int <function>wl_display_dispatch_queue</function></funcdef>
> +        <paramdef>struct wl_display *<parameter>display</parameter></paramdef>
> +        <paramdef>struct wl_event_queue *<parameter>queue</parameter></paramdef>
> +      </funcprototype>
> +
> +      <funcprototype>
> +        <funcdef>
> +          int <function>wl_display_dispatch_queue_pending</function>
> +        </funcdef>
> +        <paramdef>struct wl_display *<parameter>display</parameter></paramdef>
> +        <paramdef>struct wl_event_queue *<parameter>queue</parameter></paramdef>
> +      </funcprototype>
> +
> +    </funcsynopsis>
> +  </refsynopsisdiv>
> +
> +  <refsect1>
> +  <title>Description</title>
> +    <para>
> +      <function>wl_display_dispatch</function> dispatches all the incoming
> +      events on the display's main queue. If no events were already queued, it
> +      blocks until there are events to read from the display fd. Calling this
> +      function makes the current thread the main display thread.
> +    </para>
> +
> +    <para>
> +      <function>wl_display_dispatch_pending</function> dispatches all the
> +      incoming events on the display's main queue. If no events were already
> +      queued, it does not attempt to read the display fd, i.e. won't block.
> +      Calling this function makes the current thread the main display thread.
> +    </para>
> +
> +    <para>
> +      <function>wl_display_dispatch_queue</function> dispatches all the
> +      incoming events on the queue specified by <varname>queue</varname>. If
> +      no events were already queued, this function will block until there are
> +      any events to dispatch. If it is called from the main display thread, it
> +      will attempt to read from the display fd. If it is called from other
> +      threads it will wait until the main display thread has queued up events
> +      on the specified queue.
> +    </para>
> +
> +    <para>
> +      <function>wl_display_dispatch_queue_pending</function> dispatches all the
> +      incoming events on the queue specified by <varname>queue</varname>. If no
> +      events were already queued, it does not attempt to read the display fd
> +      nor wait for the main display thread to queue events, i.e. it won't block.
> +    </para>
> +  </refsect1>
> +
> +  <refsect1>
> +    <title>Return Value</title>
> +    <para>
> +      On success, these calls return the number of dispatched events. On error,
> +      -1 is returned and <varname>errno</varname> is set appropriately.
> +    </para>
> +  </refsect1>
> +
> +  <refsect1>
> +    <title>See Also</title>
> +    <para>
> +
> +      <citerefentry>
> +        <refentrytitle>wayland-client</refentrytitle>
> +        <manvolnum>7</manvolnum>
> +      </citerefentry>,
> +
> +      <citerefentry>
> +        <refentrytitle>wl_display_connect</refentrytitle>
> +        <manvolnum>3</manvolnum>
> +      </citerefentry>,
> +
> +      <citerefentry>
> +        <refentrytitle>wl_display_roundtrip</refentrytitle>
> +        <manvolnum>3</manvolnum>
> +      </citerefentry>
> +
> +    </para>
> +  </refsect1>
> +</refentry>
>