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

[Bill Spitzak]

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