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

[Peter Hutterer]

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