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

[Pekka Paalanen]

On Thu, 4 Dec 2014 07:49:59 +1000
Peter Hutterer <peter.hutterer at 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