[PATCH 6/9] doc: Added \code tags around sample code in doxygen comments
Pekka Paalanen
ppaalanen at gmail.com
Tue Nov 25 23:51:32 PST 2014
On Tue, 25 Nov 2014 09:46:17 -0800
Bill Spitzak <spitzak at gmail.com> wrote:
> On 11/25/2014 06:47 AM, Pekka Paalanen wrote:
> > On Tue, 11 Nov 2014 18:42:59 -0800
> > Bill Spitzak <spitzak at gmail.com> wrote:
> >
> >> Also removed \comment and used C++ comments. There does not appear
> >> to be any other way to put comments into code samples.
> >> ---
> >> src/wayland-client.c | 25 ++++++++++++++-----------
> >> src/wayland-server.h | 8 ++++----
> >> src/wayland-util.h | 30 ++++++++++++++----------------
> >> 3 files changed, 32 insertions(+), 31 deletions(-)
> >>
> >> diff --git a/src/wayland-client.c b/src/wayland-client.c
> >> index 01629e0..21fc3e9 100644
> >> --- a/src/wayland-client.c
> >> +++ b/src/wayland-client.c
> >> @@ -1321,10 +1321,12 @@ wl_display_prepare_read_queue(struct wl_display *display,
> >> * it will assume the file descriptor is readable and read events from
> >> * the fd by calling wl_display_dispatch(). Simplified, we have:
> >> *
> >> - * wl_display_dispatch_pending(display);
> >> - * wl_display_flush(display);
> >> - * poll(fds, nfds, -1);
> >> - * wl_display_dispatch(display);
> >> + * \code
> >> + * wl_display_dispatch_pending(display);
> >> + * wl_display_flush(display);
> >> + * poll(fds, nfds, -1);
> >> + * wl_display_dispatch(display);
> >> + * \endcode
> >> *
> >> * There are two races here: first, before blocking in poll(), the fd
> >> * could become readable and another thread reads the events. Some of
> >> @@ -1339,13 +1341,14 @@ wl_display_prepare_read_queue(struct wl_display *display,
> >> * fds in the event loop.
> >> *
> >> * A correct sequence would be:
> >> - *
> >> - * while (wl_display_prepare_read(display) != 0)
> >> - * wl_display_dispatch_pending(display);
> >> - * wl_display_flush(display);
> >> - * poll(fds, nfds, -1);
> >> - * wl_display_read_events(display);
> >> - * wl_display_dispatch_pending(display);
> >> + * \code
> >> + * while (wl_display_prepare_read(display) != 0)
> >> + * wl_display_dispatch_pending(display);
> >> + * wl_display_flush(display);
> >> + * poll(fds, nfds, -1);
> >> + * wl_display_read_events(display);
> >> + * wl_display_dispatch_pending(display);
> >> + * \endcode
> >> *
> >> * Here we call wl_display_prepare_read(), which ensures that between
> >> * returning from that call and eventually calling
> >> diff --git a/src/wayland-server.h b/src/wayland-server.h
> >> index 38855c9..af2f03d 100644
> >> --- a/src/wayland-server.h
> >> +++ b/src/wayland-server.h
> >> @@ -144,18 +144,18 @@ wl_client_post_no_memory(struct wl_client *client);
> >> * listener should be done through provided accessor methods. A listener can
> >> * only listen to one signal at a time.
> >> *
> >> - * ~~~
> >> + * \code
> >> * struct wl_listener your_listener;
> >> *
> >> * 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
> >> *
> >> * If the listener is part of a larger struct, #wl_container_of can be used
> >> * to retrieve a pointer to it:
> >> diff --git a/src/wayland-util.h b/src/wayland-util.h
> >> index 05e50dd..46f9a81 100644
> >> --- a/src/wayland-util.h
> >> +++ b/src/wayland-util.h
> >> @@ -88,8 +88,7 @@ struct wl_interface {
> >> * "item_t", and the item member as "struct wl_list link".
> >> *
> >> * The following code will initialize a list:
> >> - *
> >> - * ~~~
> >> + * \code
> >> * struct wl_list foo_list;
> >> *
> >> * struct item_t {
> >> @@ -99,20 +98,19 @@ struct wl_interface {
> >> * struct item_t item1, item2, item3;
> >> *
> >> * wl_list_init(&foo_list);
> >> - * wl_list_insert(&foo_list, &item1.link); \comment{Pushes item1 at the head}
> >> - * wl_list_insert(&foo_list, &item2.link); \comment{Pushes item2 at the head}
> >> - * wl_list_insert(&item2.link, &item3.link); \comment{Pushes item3 after item2}
> >> - * ~~~
> >> + * wl_list_insert(&foo_list, &item1.link); // Pushes item1 at the head
> >> + * wl_list_insert(&foo_list, &item2.link); // Pushes item2 at the head
> >> + * wl_list_insert(&item2.link, &item3.link); // Pushes item3 after item2
> >> + * \endcode
> >> *
> >> * The list now looks like [item2, item3, item1]
> >> *
> >> - * Will iterate the list in ascending order:
> >> - *
> >> + * Iterate the list in ascending order:
> >> * \code
> >> - * item_t *item;
> >> - * wl_list_for_each(item, foo_list, link) {
> >> - * Do_something_with_item(item);
> >> - * }
> >> + * item_t *item;
> >> + * wl_list_for_each(item, foo_list, link) {
> >> + * Do_something_with_item(item);
> >> + * }
> >> * \endcode
> >> */
> >> struct wl_list {
> >> @@ -138,10 +136,10 @@ void wl_list_insert_list(struct wl_list *list, struct wl_list *other);
> >> * To demonstrate, the following example retrieves a pointer to
> >> * `example_container` given only its `destroy_listener` member:
> >> *
> >> - * ~~~
> >> + * \code
> >> * struct example_container {
> >> * struct wl_listener destroy_listener;
> >> - * \comment{other members...}
> >> + * // other members...
> >> * };
> >> *
> >> * void example_container_destroy(struct wl_listener *listener, void *data)
> >> @@ -149,9 +147,9 @@ void wl_list_insert_list(struct wl_list *list, struct wl_list *other);
> >> * struct example_container *ctr;
> >> *
> >> * ctr = wl_container_of(listener, ctr, destroy_listener);
> >> - * \comment{destroy ctr...}
> >> + * // destroy ctr...
> >> * }
> >> - * ~~~
> >> + * \endcode
> >> *
> >> * \param ptr A valid pointer to the contained item.
> >> *
> >
> > Hi,
> >
> > this patch causes stars to appear in the beginning of the code lines,
> > where there previously were none (the first wl_list example). It also
> > causes the latter wl_list example to be indented while the first one is
> > not.
> >
> > But it's still an improvement in general.
>
> Let me take a look at that.
>
> Though I suspect \code is really literal. I was surprised that there was
> no \comment-like command. This may mean the stars have to be removed
> from the comment.
What \comment-line command are you looking for?
I see you reformatted
> >> - * wl_list_insert(&foo_list, &item1.link); \comment{Pushes item1 at the head}
but I assume you mean something else?
Thanks,
pq
More information about the wayland-devel
mailing list