[1/4] doc: use markdown tildes for code blocks

Submitted by Bill Spitzak on Dec. 3, 2014, 2:29 a.m.

Details

Message ID 1417573776-4829-1-git-send-email-spitzak@gmail.com
State Rejected
Headers show

Not browsing as part of any series.

Commit Message

Bill Spitzak Dec. 3, 2014, 2:29 a.m.
This requires doxygen 1.8 or newer.
I could not figure out how to make configure.ac test the doxygen
version number. It appears to be really complex. So it will run with
any version of doxygen and the doc output is somewhat mangled.
---
 src/wayland-client.c |   14 +++++++-------
 src/wayland-server.h |   16 ++++++++--------
 src/wayland-util.h   |   24 +++++++++++++-----------
 3 files changed, 28 insertions(+), 26 deletions(-)

Patch hide | download patch | download mbox

diff --git a/src/wayland-client.c b/src/wayland-client.c
index 36380fe..9dddb29 100644
--- a/src/wayland-client.c
+++ b/src/wayland-client.c
@@ -1326,12 +1326,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:
  *
- * \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
@@ -1346,14 +1346,15 @@  wl_display_prepare_read_queue(struct wl_display *display,
  * fds in the event loop.
  *
  * A correct sequence would be:
- * \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
@@ -1602,7 +1603,7 @@  wl_display_get_error(struct wl_display *display)
  *                   still valid; the client must know if it deleted the object.
  * \return           The error code as defined in the interface specification.
  *
- * \code
+ * ~~~
  * int err = wl_display_get_error(display);
  *
  * if (err == EPROTO) {
@@ -1611,8 +1612,7 @@  wl_display_get_error(struct wl_display *display)
  * }
  *
  * ...
- *
- *  \endcode
+ * ~~~
  */
 WL_EXPORT uint32_t
 wl_display_get_protocol_error(struct wl_display *display,
diff --git a/src/wayland-server.h b/src/wayland-server.h
index af2f03d..22185e8 100644
--- a/src/wayland-server.h
+++ b/src/wayland-server.h
@@ -144,36 +144,36 @@  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;
  *
- * // Direct access
+ * \comment{Direct access}
  * wl_signal_add(&some_object->destroy_signal, &your_listener);
  *
- * // Accessor access
+ * \comment{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:
  *
- * \code
+ * ~~~
  * void your_listener(struct wl_listener *listener, void *data)
  * {
  * 	struct your_data *data;
  *
  * 	your_data = wl_container_of(listener, data, your_member_name);
  * }
- * \endcode
+ * ~~~
  *
  * If you need to remove a listener from a signal, use wl_list_remove().
  *
- * \code
+ * ~~~
  * wl_list_remove(&your_listener.link);
- * \endcode
+ * ~~~
  *
  * \sa wl_signal
  */
diff --git a/src/wayland-util.h b/src/wayland-util.h
index a4b22b5..d61ce0a 100644
--- a/src/wayland-util.h
+++ b/src/wayland-util.h
@@ -88,7 +88,8 @@  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 {
@@ -98,20 +99,21 @@  struct wl_interface {
  * struct item_t item1, item2, item3;
  *
  * wl_list_init(&foo_list);
- * 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
+ * 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}
+ * ~~~
  *
  * The list now looks like [item2, item3, item1]
  *
  * Iterate the list in ascending order:
- * \code
+ *
+ * ~~~
  * item_t *item;
  * wl_list_for_each(item, foo_list, link) {
  * 	Do_something_with_item(item);
  * }
- * \endcode
+ * ~~~
  */
 struct wl_list {
 	struct wl_list *prev;
@@ -136,10 +138,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;
- *     // other members...
+ *     \comment{other members...}
  * };
  *
  * void example_container_destroy(struct wl_listener *listener, void *data)
@@ -147,9 +149,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);
- *     // destroy ctr...
+ *     \comment{destroy ctr...}
  * }
- * \endcode
+ * ~~~
  *
  * \param ptr A valid pointer to the contained item.
  *

Comments

On 12/02/2014 06:29 PM, Bill Spitzak wrote:
> This requires doxygen 1.8 or newer.

FYI this will cut off support for RHEL6 and corresponding distros such
as CentOS and Scientific Linux (I had to track this for my prior day job).

On the other hand, RHEL7 is up to Doxygen 1.8.5 so we're good in that
regard. (Does there happen to be a page listing what Wayland is
supported on/targeting and not?)


> I could not figure out how to make configure.ac test the doxygen
> version number. It appears to be really complex. So it will run with
> any version of doxygen and the doc output is somewhat mangled.

I'll take a peek at that. Seems familiar.
On Tue, Dec 02, 2014 at 06:29:33PM -0800, Bill Spitzak wrote:
> This requires doxygen 1.8 or newer.
> I could not figure out how to make configure.ac test the doxygen
> version number. It appears to be really complex. So it will run with
> any version of doxygen and the doc output is somewhat mangled.

I'm missing the reasoning here: why not leave code/endcode? was this
explained in some other thread?

Cheers,
   Peter

> ---
>  src/wayland-client.c |   14 +++++++-------
>  src/wayland-server.h |   16 ++++++++--------
>  src/wayland-util.h   |   24 +++++++++++++-----------
>  3 files changed, 28 insertions(+), 26 deletions(-)
> 
> diff --git a/src/wayland-client.c b/src/wayland-client.c
> index 36380fe..9dddb29 100644
> --- a/src/wayland-client.c
> +++ b/src/wayland-client.c
> @@ -1326,12 +1326,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:
>   *
> - * \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
> @@ -1346,14 +1346,15 @@ wl_display_prepare_read_queue(struct wl_display *display,
>   * fds in the event loop.
>   *
>   * A correct sequence would be:
> - * \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
> @@ -1602,7 +1603,7 @@ wl_display_get_error(struct wl_display *display)
>   *                   still valid; the client must know if it deleted the object.
>   * \return           The error code as defined in the interface specification.
>   *
> - * \code
> + * ~~~
>   * int err = wl_display_get_error(display);
>   *
>   * if (err == EPROTO) {
> @@ -1611,8 +1612,7 @@ wl_display_get_error(struct wl_display *display)
>   * }
>   *
>   * ...
> - *
> - *  \endcode
> + * ~~~
>   */
>  WL_EXPORT uint32_t
>  wl_display_get_protocol_error(struct wl_display *display,
> diff --git a/src/wayland-server.h b/src/wayland-server.h
> index af2f03d..22185e8 100644
> --- a/src/wayland-server.h
> +++ b/src/wayland-server.h
> @@ -144,36 +144,36 @@ 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;
>   *
> - * // Direct access
> + * \comment{Direct access}
>   * wl_signal_add(&some_object->destroy_signal, &your_listener);
>   *
> - * // Accessor access
> + * \comment{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:
>   *
> - * \code
> + * ~~~
>   * void your_listener(struct wl_listener *listener, void *data)
>   * {
>   * 	struct your_data *data;
>   *
>   * 	your_data = wl_container_of(listener, data, your_member_name);
>   * }
> - * \endcode
> + * ~~~
>   *
>   * If you need to remove a listener from a signal, use wl_list_remove().
>   *
> - * \code
> + * ~~~
>   * wl_list_remove(&your_listener.link);
> - * \endcode
> + * ~~~
>   *
>   * \sa wl_signal
>   */
> diff --git a/src/wayland-util.h b/src/wayland-util.h
> index a4b22b5..d61ce0a 100644
> --- a/src/wayland-util.h
> +++ b/src/wayland-util.h
> @@ -88,7 +88,8 @@ 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 {
> @@ -98,20 +99,21 @@ struct wl_interface {
>   * struct item_t item1, item2, item3;
>   *
>   * wl_list_init(&foo_list);
> - * 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
> + * 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}
> + * ~~~
>   *
>   * The list now looks like [item2, item3, item1]
>   *
>   * Iterate the list in ascending order:
> - * \code
> + *
> + * ~~~
>   * item_t *item;
>   * wl_list_for_each(item, foo_list, link) {
>   * 	Do_something_with_item(item);
>   * }
> - * \endcode
> + * ~~~
>   */
>  struct wl_list {
>  	struct wl_list *prev;
> @@ -136,10 +138,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;
> - *     // other members...
> + *     \comment{other members...}
>   * };
>   *
>   * void example_container_destroy(struct wl_listener *listener, void *data)
> @@ -147,9 +149,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);
> - *     // destroy ctr...
> + *     \comment{destroy ctr...}
>   * }
> - * \endcode
> + * ~~~
>   *
>   * \param ptr A valid pointer to the contained item.
>   *
> -- 
> 1.7.9.5
On 12/02/2014 07:45 PM, Peter Hutterer wrote:
> On Tue, Dec 02, 2014 at 06:29:33PM -0800, Bill Spitzak wrote:
>> This requires doxygen 1.8 or newer.
>> I could not figure out how to make configure.ac test the doxygen
>> version number. It appears to be really complex. So it will run with
>> any version of doxygen and the doc output is somewhat mangled.
>
> I'm missing the reasoning here: why not leave code/endcode? was this
> explained in some other thread?

The main reason is the \comment does not seem to work in code/endcode, 
but works in the markdown. I also discovered that a code command breaks 
the tilde version (by making it not remove the asterisks), so you have 
to use all of one or the other consistently. Both of these are certainly 
Doxygen bugs.

Another reason is that this is reverting a change I previously made.

Some people may prefer the markdown/wiki style rather than commands, as
it makes the comments more readable directly. Besides the tildes, the 
same recent versions support indentation by 4 spaces to indicate code, 
which is common in wiki markup. That may be another alternative.

I'm not sure if this is all enough of a reason however. As pointed out 
by others this makes it not work with doxygen < 1.8 and there are 
several systems that provide earlier versions by default, including 
Ubuntu LTS 12.04. And I noticed in some libinput patches just posted 
that code/endcode is used in them.

Any opinions? I don't know which way is better.
On Wed, Dec 03, 2014 at 12:37:40PM -0800, Bill Spitzak wrote:
> 
> 
> On 12/02/2014 07:45 PM, Peter Hutterer wrote:
> >On Tue, Dec 02, 2014 at 06:29:33PM -0800, Bill Spitzak wrote:
> >>This requires doxygen 1.8 or newer.
> >>I could not figure out how to make configure.ac test the doxygen
> >>version number. It appears to be really complex. So it will run with
> >>any version of doxygen and the doc output is somewhat mangled.
> >
> >I'm missing the reasoning here: why not leave code/endcode? was this
> >explained in some other thread?
> 
> The main reason is the \comment does not seem to work in code/endcode, but

what is \comment? I can't find it in the doxygen tag list.

> works in the markdown. I also discovered that a code command breaks the
> tilde version (by making it not remove the asterisks), so you have to use
> all of one or the other consistently. Both of these are certainly Doxygen
> bugs.
> 
> Another reason is that this is reverting a change I previously made.
> 
> Some people may prefer the markdown/wiki style rather than commands, as
> it makes the comments more readable directly. Besides the tildes, the same
> recent versions support indentation by 4 spaces to indicate code, which is
> common in wiki markup. That may be another alternative.
> 
> I'm not sure if this is all enough of a reason however. As pointed out by
> others this makes it not work with doxygen < 1.8 and there are several
> systems that provide earlier versions by default, including Ubuntu LTS
> 12.04. And I noticed in some libinput patches just posted that code/endcode
> is used in them.

yeah, I've used code/endcode in libinput and libevdev but for no other
reason than that was what google came up with when looking for it (I think
it also pre-dates 1.8.1)

> Any opinions? I don't know which way is better.

I'd say go with the one that's more compatible (code/endcode) and work
around the lack of comment support.

Cheers,
   Peter
On 12/03/2014 01:49 PM, Peter Hutterer wrote:

> what is \comment? I can't find it in the doxygen tag list.

That stumped me for a while, too. It's an "alias" defined in the 
wayland.doxygen file. As far as I can tell aliases are not really 
commands, they are instead more like macros. This explains why they work 
in the ~~~ while no other commands do. And it seems the code command 
does disable them. Possibly one of these is a bug.

>> Any opinions? I don't know which way is better.
>
> I'd say go with the one that's more compatible (code/endcode) and work
> around the lack of comment support.

Okay I think this patch should be dropped, and doxygen 1.8 is not required.

I did some web searches, and the consensus is that Doxygen has done a 
great job of making it impossible to put a C-style comment into a code 
sample. Either use C++ comments (which is what I did), or maybe 
something can be done by the xslt translator (but it won't show up in 
the man pages).
On Wed, Dec 03, 2014 at 02:20:50PM -0800, Bill Spitzak wrote:
> On 12/03/2014 01:49 PM, Peter Hutterer wrote:
> 
> >what is \comment? I can't find it in the doxygen tag list.
> 
> That stumped me for a while, too. It's an "alias" defined in the
> wayland.doxygen file. As far as I can tell aliases are not really commands,
> they are instead more like macros. This explains why they work in the ~~~
> while no other commands do. And it seems the code command does disable them.
> Possibly one of these is a bug.
> 
> >>Any opinions? I don't know which way is better.
> >
> >I'd say go with the one that's more compatible (code/endcode) and work
> >around the lack of comment support.
> 
> Okay I think this patch should be dropped, and doxygen 1.8 is not required.
> 
> I did some web searches, and the consensus is that Doxygen has done a great
> job of making it impossible to put a C-style comment into a code sample.

doxygen is designed for source file commenting. you couldn't compile a
nested C-style comment, doxygen doesn't come into effect here anyway.

Cheers,
   Peter

> Either use C++ comments (which is what I did), or maybe something can be
> done by the xslt translator (but it won't show up in the man pages).
>
On 12/03/2014 02:37 PM, Peter Hutterer wrote:

>> I did some web searches, and the consensus is that Doxygen has done a great
>> job of making it impossible to put a C-style comment into a code sample.
>
> doxygen is designed for source file commenting. you couldn't compile a
> nested C-style comment, doxygen doesn't come into effect here anyway.

What I meant is there does not appear to be any way to get doxygen to 
print an asterisk and slash next to each other in the output if the 
input is inside a C comment. I did not expect a literal C comment to work.
On Tue, 02 Dec 2014 19:02:12 -0800
"Jon A. Cruz" <jonc@osg.samsung.com> wrote:

> On 12/02/2014 06:29 PM, Bill Spitzak wrote:
> > This requires doxygen 1.8 or newer.
> 
> FYI this will cut off support for RHEL6 and corresponding distros such
> as CentOS and Scientific Linux (I had to track this for my prior day job).
> 
> On the other hand, RHEL7 is up to Doxygen 1.8.5 so we're good in that
> regard. (Does there happen to be a page listing what Wayland is
> supported on/targeting and not?)

I don't think we have any policy set on that. We do what we think is
reasonable, and get bug reports or patches if people disagree after the
fact.


Thanks,
pq
On Thu, 4 Dec 2014 07:49:59 +1000
Peter Hutterer <peter.hutterer@who-t.net> wrote:

> On Wed, Dec 03, 2014 at 12:37:40PM -0800, Bill Spitzak wrote:
> > 
> > 
> > On 12/02/2014 07:45 PM, Peter Hutterer wrote:
> > >On Tue, Dec 02, 2014 at 06:29:33PM -0800, Bill Spitzak wrote:
> > >>This requires doxygen 1.8 or newer.
> > >>I could not figure out how to make configure.ac test the doxygen
> > >>version number. It appears to be really complex. So it will run with
> > >>any version of doxygen and the doc output is somewhat mangled.
> > >
> > >I'm missing the reasoning here: why not leave code/endcode? was this
> > >explained in some other thread?
> > 
> > The main reason is the \comment does not seem to work in code/endcode, but
> 
> what is \comment? I can't find it in the doxygen tag list.
> 
> > works in the markdown. I also discovered that a code command breaks the
> > tilde version (by making it not remove the asterisks), so you have to use
> > all of one or the other consistently. Both of these are certainly Doxygen
> > bugs.
> > 
> > Another reason is that this is reverting a change I previously made.
> > 
> > Some people may prefer the markdown/wiki style rather than commands, as
> > it makes the comments more readable directly. Besides the tildes, the same
> > recent versions support indentation by 4 spaces to indicate code, which is
> > common in wiki markup. That may be another alternative.
> > 
> > I'm not sure if this is all enough of a reason however. As pointed out by
> > others this makes it not work with doxygen < 1.8 and there are several
> > systems that provide earlier versions by default, including Ubuntu LTS
> > 12.04. And I noticed in some libinput patches just posted that code/endcode
> > is used in them.
> 
> yeah, I've used code/endcode in libinput and libevdev but for no other
> reason than that was what google came up with when looking for it (I think
> it also pre-dates 1.8.1)
> 
> > Any opinions? I don't know which way is better.
> 
> I'd say go with the one that's more compatible (code/endcode) and work
> around the lack of comment support.

Hi Peter,

do you have any suggestions on how to get rid of the asterisks in front
of code examples?

Here is an example from the HTML which was generated from
wayland-util.h:90 with the code/endcode, i.e. what's right now in
upstream (962de0d0cc53f6ec737d18e6f8f9483d05e41dbb):

<p>The following code will initialize a list: </p><pre class="programlisting">* struct <a class="link" href="ch05.html#structwl__list">wl_list</a> foo_list;
*
* struct item_t {
*       int foo;

Introducing the asterisks was another reason why I thought converting
from ~~~ to code/endcode was to the worse.

According to git-grep, there are no ~~~ anywhere, so I don't think the
mixing of that and code/endcode is the issue here.

How should we work around the lack of comment support?

Should we just ignore our coding style when writing code examples in
Doxygen comments? Or maybe there is some doxygen.conf option we missed?

Doxygen 1.8.5.


Thanks,
pq
On 12/05/2014 06:44 AM, Pekka Paalanen wrote:

> do you have any suggestions on how to get rid of the asterisks in front
> of code examples?

All I can say is that this appears to be a Doxygen bug, and it depends 
both on the version of Doxygen and on what commands have been processed 
by Doxygen before it encounters this. For me 1.8.6 and 1.7.6.1 do not 
produce this artifact with the current git head.

I did see 1.8.6 produce this, but only if a \code was first, then a ~~~, 
and then a \comment inside that. Obviously it is easier to trigger this 
but that was the only instance I found. You said you are using 1.8.5 so 
maybe it has this bug.

> How should we work around the lack of comment support?
>
> Should we just ignore our coding style when writing code examples in
> Doxygen comments?

I'm uncertain if removing the asterisks is even a good solution. If you 
have a line in there like "*pointer = value;" it apparently still 
removes the asterisk!

> Or maybe there is some doxygen.conf option we missed?

I doubt it.
On Fri, Dec 05, 2014 at 12:53:28PM -0800, Bill Spitzak wrote:
> On 12/05/2014 06:44 AM, Pekka Paalanen wrote:
> 
> >do you have any suggestions on how to get rid of the asterisks in front
> >of code examples?
> 
> All I can say is that this appears to be a Doxygen bug, and it depends both
> on the version of Doxygen and on what commands have been processed by
> Doxygen before it encounters this. For me 1.8.6 and 1.7.6.1 do not produce
> this artifact with the current git head.
> 
> I did see 1.8.6 produce this, but only if a \code was first, then a ~~~, and
> then a \comment inside that. Obviously it is easier to trigger this but that
> was the only instance I found. You said you are using 1.8.5 so maybe it has
> this bug.

I'm pretty sure it's a bug too. I saw this in libevdev too but it
disappeared after upgrading to f21. not sure what exact version of doxygen
fixes it, ETIME to bisecty that atm, sorry.

I'd leave them in for now and wait for doxygen to fix itself on your
machine :)

Cheers,
   Peter

> 
> >How should we work around the lack of comment support?
> >
> >Should we just ignore our coding style when writing code examples in
> >Doxygen comments?
> 
> I'm uncertain if removing the asterisks is even a good solution. If you have
> a line in there like "*pointer = value;" it apparently still removes the
> asterisk!
> 
> >Or maybe there is some doxygen.conf option we missed?
> 
> I doubt it.
On Fri, 05 Dec 2014 12:53:28 -0800
Bill Spitzak <spitzak@gmail.com> wrote:

> On 12/05/2014 06:44 AM, Pekka Paalanen wrote:
> 
> > do you have any suggestions on how to get rid of the asterisks in front
> > of code examples?
> 
> All I can say is that this appears to be a Doxygen bug, and it depends 
> both on the version of Doxygen and on what commands have been processed 
> by Doxygen before it encounters this. For me 1.8.6 and 1.7.6.1 do not 
> produce this artifact with the current git head.
> 
> I did see 1.8.6 produce this, but only if a \code was first, then a ~~~, 
> and then a \comment inside that. Obviously it is easier to trigger this 
> but that was the only instance I found. You said you are using 1.8.5 so 
> maybe it has this bug.

Yes indeed:
https://bugzilla.gnome.org/show_bug.cgi?id=707567

Upgrading to 1.8.6 solved the problem for me, and since I'm probably
the one to be uploading the generated docs to the Wayland website, I'd
say problem solved.


Thanks,
pq
However I think the decision was to only require Doxygen 1.6 and 
therefore the tildes don't work, and you must use \code. Is this 
correct? This is what is currently in git head.

On 12/08/2014 01:35 AM, Pekka Paalanen wrote:
> On Fri, 05 Dec 2014 12:53:28 -0800
> Bill Spitzak <spitzak@gmail.com> wrote:
>
>> On 12/05/2014 06:44 AM, Pekka Paalanen wrote:
>>
>>> do you have any suggestions on how to get rid of the asterisks in front
>>> of code examples?
>>
>> All I can say is that this appears to be a Doxygen bug, and it depends
>> both on the version of Doxygen and on what commands have been processed
>> by Doxygen before it encounters this. For me 1.8.6 and 1.7.6.1 do not
>> produce this artifact with the current git head.
>>
>> I did see 1.8.6 produce this, but only if a \code was first, then a ~~~,
>> and then a \comment inside that. Obviously it is easier to trigger this
>> but that was the only instance I found. You said you are using 1.8.5 so
>> maybe it has this bug.
>
> Yes indeed:
> https://bugzilla.gnome.org/show_bug.cgi?id=707567
>
> Upgrading to 1.8.6 solved the problem for me, and since I'm probably
> the one to be uploading the generated docs to the Wayland website, I'd
> say problem solved.
>
>
> Thanks,
> pq
>
On Mon, 08 Dec 2014 11:06:00 -0800
Bill Spitzak <spitzak@gmail.com> wrote:

> However I think the decision was to only require Doxygen 1.6 and 
> therefore the tildes don't work, and you must use \code. Is this 
> correct? This is what is currently in git head.

There is no tilde mark-up in upstream at the moment.

If you know tildes would not work with doxygen 1.6, then we should keep
using code/endcode.

The comment style in the example code in documentation for wl_list is
now in C++(/C99?) style, but that's ok, everyone can read it.


Thanks,
pq