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

Submitted by Bill Spitzak on Nov. 12, 2014, 2:42 a.m.

Details

Message ID 1415760182-19568-7-git-send-email-spitzak@gmail.com
State Accepted
Commit 40aa80a4082975d1598f4896a751c0562be9016b
Headers show

Not browsing as part of any series.

Commit Message

Bill Spitzak Nov. 12, 2014, 2:42 a.m.
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(-)

Patch hide | download patch | download mbox

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.
  *

Comments

On Tue, 11 Nov 2014 18:42:59 -0800
Bill Spitzak <spitzak@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.


Thanks,
pq
On 11/25/2014 06:47 AM, Pekka Paalanen wrote:
> On Tue, 11 Nov 2014 18:42:59 -0800
> Bill Spitzak <spitzak@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.
On Tue, 25 Nov 2014 09:46:17 -0800
Bill Spitzak <spitzak@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@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
On 11/25/2014 11:51 PM, Pekka Paalanen wrote:

> 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?

No I meant that. I thought somebody had made the comment command to 
produce "/* text */". Apparently however this is a holdover from javadoc 
or something and doxygen does not do it.

I did some web searching, and everybody says the only way to do a 
comment is to use a different comment style that can be nested. Since 
C-style comments don't nest you have to use something else if the 
doxygen comment is C-style. The doxygen code tag appears to make it 
entirely literal, the only thing it recognizes is \endcode.

Not sure if it would be acceptable to use C++ comments in Wayland 
source, but that would be a solution. It was how I got around this 
problem before.

Another solution is to get Doxygen to produce code-like output but where 
commands can be interpreted. Using <tt> and replacing every space with 
<sp/> and every newline with <br/> works but is really ugly.
On Wed, 26 Nov 2014 10:32:56 -0800
Bill Spitzak <spitzak@gmail.com> wrote:

> On 11/25/2014 11:51 PM, Pekka Paalanen wrote:
> 
> > 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?
> 
> No I meant that. I thought somebody had made the comment command to 
> produce "/* text */". Apparently however this is a holdover from javadoc 
> or something and doxygen does not do it.

Sorry?

doc/doxygen/wayland.doxygen.in has:
ALIASES                += comment{1}="/* \1 *<!-- -->/"

What's wrong with that?

> I did some web searching, and everybody says the only way to do a 
> comment is to use a different comment style that can be nested. Since 
> C-style comments don't nest you have to use something else if the 
> doxygen comment is C-style. The doxygen code tag appears to make it 
> entirely literal, the only thing it recognizes is \endcode.
> 
> Not sure if it would be acceptable to use C++ comments in Wayland 
> source, but that would be a solution. It was how I got around this 
> problem before.
> 
> Another solution is to get Doxygen to produce code-like output but where 
> commands can be interpreted. Using <tt> and replacing every space with 
> <sp/> and every newline with <br/> works but is really ugly.
> 

FWIW, with the Doxygen version I have, that \comment{foo} did
produce /* foo */ in the output, just like one would expect, and it
worked nicely where it was used.

Our style is to use traditional C comments, not C++.


Thanks,
pq
More experiments, this time with Doxygen 1.8.6. Apparently the ~~~ 
markers (called "Markdown support" or "Fenced code blocks") were 
introduced in 1.8. Maybe config needs to check for this? Indeed ~~~ 
produces code samples now.

It appears aliases (but not other commands) work inside ~~~. They do not 
work inside \code.

There is a bug that causes asterisks: if a \code is anywhere earlier in 
the source code (ie it can be in a different comment block) then when a 
\comment is encountered in ~~~ it puts the asterisks on the start of 
every remaining line. I would assume this is a Doxygen bug.

I think the fix is to remove \code everywhere and use the (nicer-looking 
imho) ~~~ delimiters. It may also be useful to require the new Doxygen 
in config.

On 11/27/2014 02:53 AM, Pekka Paalanen wrote:
> On Wed, 26 Nov 2014 10:32:56 -0800
> Bill Spitzak <spitzak@gmail.com> wrote:
>
>> On 11/25/2014 11:51 PM, Pekka Paalanen wrote:
>>
>>> 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?
>>
>> No I meant that. I thought somebody had made the comment command to
>> produce "/* text */". Apparently however this is a holdover from javadoc
>> or something and doxygen does not do it.
>
> Sorry?
>
> doc/doxygen/wayland.doxygen.in has:
> ALIASES                += comment{1}="/* \1 *<!-- -->/"
>
> What's wrong with that?
>
>> I did some web searching, and everybody says the only way to do a
>> comment is to use a different comment style that can be nested. Since
>> C-style comments don't nest you have to use something else if the
>> doxygen comment is C-style. The doxygen code tag appears to make it
>> entirely literal, the only thing it recognizes is \endcode.
>>
>> Not sure if it would be acceptable to use C++ comments in Wayland
>> source, but that would be a solution. It was how I got around this
>> problem before.
>>
>> Another solution is to get Doxygen to produce code-like output but where
>> commands can be interpreted. Using <tt> and replacing every space with
>> <sp/> and every newline with <br/> works but is really ugly.
>>
>
> FWIW, with the Doxygen version I have, that \comment{foo} did
> produce /* foo */ in the output, just like one would expect, and it
> worked nicely where it was used.
>
> Our style is to use traditional C comments, not C++.
>
>
> Thanks,
> pq
>
On Thu, 27 Nov 2014 13:00:07 -0800
Bill Spitzak <spitzak@gmail.com> wrote:

> More experiments, this time with Doxygen 1.8.6. Apparently the ~~~ 
> markers (called "Markdown support" or "Fenced code blocks") were 
> introduced in 1.8. Maybe config needs to check for this? Indeed ~~~ 
> produces code samples now.
> 
> It appears aliases (but not other commands) work inside ~~~. They do not 
> work inside \code.
> 
> There is a bug that causes asterisks: if a \code is anywhere earlier in 
> the source code (ie it can be in a different comment block) then when a 
> \comment is encountered in ~~~ it puts the asterisks on the start of 
> every remaining line. I would assume this is a Doxygen bug.
> 
> I think the fix is to remove \code everywhere and use the (nicer-looking 
> imho) ~~~ delimiters. It may also be useful to require the new Doxygen 
> in config.

Yeah, going back to ~~~ sounds good.

Doxygen 1.8.0 was released in Feb 2012. I'm not sure about making it a
hard requirement if one is building the docs, but we could at least warn
about an older version.


Thanks,
pq