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

[Bill Spitzak]

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.