[PATCH 6/9] doc: Added \code tags around sample code in doxygen comments

[Bill Spitzak]

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.