[PATCH 8/8] doc: Added % to remove some self-references from doxygen output
Peter Hutterer
peter.hutterer at who-t.net
Sun Nov 9 14:14:49 PST 2014
On Fri, Nov 07, 2014 at 05:33:38PM -0800, Bill Spitzak wrote:
> ---
> src/wayland-client.c | 14 +++++++-------
> src/wayland-client.h | 14 +++++++-------
> src/wayland-server.h | 12 ++++++------
> 3 files changed, 20 insertions(+), 20 deletions(-)
>
> diff --git a/src/wayland-client.c b/src/wayland-client.c
> index 161f14e..2126430 100644
> --- a/src/wayland-client.c
> +++ b/src/wayland-client.c
> @@ -1209,7 +1209,7 @@ cancel_read(struct wl_display *display)
> * This will read events from the file descriptor for the display.
> * This function does not dispatch events, it only reads and queues
> * events into their corresponding event queues. If no data is
> - * avilable on the file descriptor, wl_display_read_events() returns
> + * avilable on the file descriptor, %wl_display_read_events() returns
looks like there's a typo here ("avilable"), might be worth a follow-up
patch.
That aside: not a big fan of this patch, I'd prefer to see it
highlighted. The linking is excessive but at least cursive or bold would be
nice here. Then again, if it requires extra markup in the comments I'm not
sure it's worthwhile.
Rest of the series: Acked-by: Peter Hutterer <peter.hutterer at who-t.net>
Cheers,
Peter
> * immediately. To dispatch events that may have been queued, call
> * wl_display_dispatch_pending() or
> * wl_display_dispatch_queue_pending().
> @@ -1300,14 +1300,14 @@ wl_display_prepare_read_queue(struct wl_display *display,
> *
> * This function must be called before reading from the file
> * descriptor using wl_display_read_events(). Calling
> - * wl_display_prepare_read() announces the calling threads intention
> + * %wl_display_prepare_read() announces the calling threads intention
> * to read and ensures that until the thread is ready to read and
> * calls wl_display_read_events(), no other thread will read from the
> * file descriptor. This only succeeds if the event queue is empty
> * though, and if there are undispatched events in the queue, -1 is
> * returned and errno set to EAGAIN.
> *
> - * If a thread successfully calls wl_display_prepare_read(), it must
> + * If a thread successfully calls %wl_display_prepare_read(), it must
> * either call wl_display_read_events() when it's ready or cancel the
> * read intention by calling wl_display_cancel_read().
> *
> @@ -1347,11 +1347,11 @@ wl_display_prepare_read_queue(struct wl_display *display,
> * wl_display_dispatch_pending(display);
> * \endcode
> *
> - * Here we call wl_display_prepare_read(), which ensures that between
> + * Here we call %wl_display_prepare_read(), which ensures that between
> * returning from that call and eventually calling
> * wl_display_read_events(), no other thread will read from the fd and
> * queue events in our queue. If the call to
> - * wl_display_prepare_read() fails, we dispatch the pending events and
> + * %wl_display_prepare_read() fails, we dispatch the pending events and
> * try again until we're successful.
> *
> * \memberof wl_display
> @@ -1534,7 +1534,7 @@ wl_display_dispatch(struct wl_display *display)
> * to dispatch.
> *
> * To proper integrate the wayland display fd into a main loop, the
> - * client should always call \ref wl_display_dispatch_pending() and then
> + * client should always call %wl_display_dispatch_pending() and then
> * \ref wl_display_flush() prior to going back to sleep. At that point,
> * the fd typically doesn't have data so attempting I/O could block, but
> * events queued up on the main queue should be dispatched.
> @@ -1641,7 +1641,7 @@ wl_display_get_protocol_error(struct wl_display *display,
> * of bytes sent to the server is returned. On failure, this
> * function returns -1 and errno is set appropriately.
> *
> - * wl_display_flush() never blocks. It will write as much data as
> + * %wl_display_flush() never blocks. It will write as much data as
> * possible, but if all data could not be written, errno will be set
> * to EAGAIN and -1 returned. In that case, use poll on the display
> * file descriptor to wait for it to become writable again.
> diff --git a/src/wayland-client.h b/src/wayland-client.h
> index 0801a81..531871b 100644
> --- a/src/wayland-client.h
> +++ b/src/wayland-client.h
> @@ -34,14 +34,14 @@ extern "C" {
> *
> * \brief Represents a protocol object on the client side.
> *
> - * A wl_proxy acts as a client side proxy to an object existing in the
> + * A %wl_proxy acts as a client side proxy to an object existing in the
> * compositor. The proxy is responsible for converting requests made by the
> * clients with \ref wl_proxy_marshal() into Wayland's wire format. Events
> * coming from the compositor are also handled by the proxy, which will in
> * turn call the handler set with \ref wl_proxy_add_listener().
> *
> * \note With the exception of function \ref wl_proxy_set_queue(), functions
> - * accessing a \ref wl_proxy are not normally used by client code. Clients
> + * accessing a %wl_proxy are not normally used by client code. Clients
> * should normally use the higher level interface generated by the scanner to
> * interact with compositor objects.
> *
> @@ -51,17 +51,17 @@ struct wl_proxy;
> /** \class wl_display
> *
> * \brief Represents a connection to the compositor and acts as a proxy to
> - * the wl_display singleton object.
> + * the %wl_display singleton object.
> *
> - * A \ref wl_display object represents a client connection to a Wayland
> + * A %wl_display object represents a client connection to a Wayland
> * compositor. It is created with either \ref wl_display_connect() or
> * \ref wl_display_connect_to_fd(). A connection is terminated using
> * \ref wl_display_disconnect().
> *
> - * A \ref wl_display is also used as the \ref wl_proxy for the \ref wl_display
> + * A %wl_display is also used as the \ref wl_proxy for the wl_display
> * singleton object on the compositor side.
> *
> - * A \ref wl_display object handles all the data sent from and to the
> + * A %wl_display object handles all the data sent from and to the
> * compositor. When a \ref wl_proxy marshals a request, it will write its wire
> * representation to the display's write buffer. The data is sent to the
> * compositor when the client calls \ref wl_display_flush().
> @@ -71,7 +71,7 @@ struct wl_proxy;
> * added to a queue. On the dispatch step, the handler for the incoming
> * event set by the client on the corresponding \ref wl_proxy is called.
> *
> - * A \ref wl_display has at least one event queue, called the <em>main
> + * A %wl_display has at least one event queue, called the <em>main
> * queue</em>. Clients can create additional event queues with \ref
> * wl_display_create_queue() and assign \ref wl_proxy's to it. Events
> * occurring in a particular proxy are always queued in its assigned queue.
> diff --git a/src/wayland-server.h b/src/wayland-server.h
> index 3093ced..ca8dd2f 100644
> --- a/src/wayland-server.h
> +++ b/src/wayland-server.h
> @@ -134,11 +134,11 @@ wl_client_post_no_memory(struct wl_client *client);
> *
> * \brief A single listener for Wayland signals
> *
> - * wl_listener provides the means to listen for wl_signal notifications. Many
> - * Wayland objects use wl_listener for notification of significant events like
> + * %wl_listener provides the means to listen for wl_signal notifications. Many
> + * Wayland objects use %wl_listener for notification of significant events like
> * object destruction.
> *
> - * Clients should create wl_listener objects manually and can register them as
> + * Clients should create %wl_listener objects manually and can register them as
> * listeners to signals using #wl_signal_add, assuming the signal is
> * directly accessible. For opaque structs like wl_event_loop, adding a
> * listener should be done through provided accessor methods. A listener can
> @@ -149,10 +149,10 @@ wl_client_post_no_memory(struct wl_client *client);
> *
> * your_listener.notify = your_callback_method;
> *
> - * \comment{Direct access}
> + * // Direct access
> * wl_signal_add(&some_object->destroy_signal, &your_listener);
> *
> - * \comment{Accessor access}
> + * // Accessor access
> * wl_event_loop *loop = ...;
> * wl_event_loop_add_destroy_listener(loop, &your_listener);
> * \endcode
> @@ -193,7 +193,7 @@ struct wl_listener {
> * listener is removed by wl_list_remove() (or whenever the signal is
> * destroyed).
> *
> - * \sa wl_listener for more information on using wl_signal
> + * \sa wl_listener for more information on using %wl_signal
> */
> struct wl_signal {
> struct wl_list listener_list;
> --
> 1.7.9.5
>
> _______________________________________________
> 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