[PATCH 6/9] doc: Added \code tags around sample code in doxygen comments

[Bill Spitzak]

More experiments, this time with Doxygen 1.8.6. Apparently the ~~~ 
markers (called "Markdown support" or "Fenced code blocks") were 
introduced in 1.8. Maybe config needs to check for this? Indeed ~~~ 
produces code samples now.

It appears aliases (but not other commands) work inside ~~~. They do not 
work inside \code.

There is a bug that causes asterisks: if a \code is anywhere earlier in 
the source code (ie it can be in a different comment block) then when a 
\comment is encountered in ~~~ it puts the asterisks on the start of 
every remaining line. I would assume this is a Doxygen bug.

I think the fix is to remove \code everywhere and use the (nicer-looking 
imho) ~~~ delimiters. It may also be useful to require the new Doxygen 
in config.

On 11/27/2014 02:53 AM, Pekka Paalanen wrote:
> On Wed, 26 Nov 2014 10:32:56 -0800
> Bill Spitzak <spitzak at gmail.com> wrote:
>
>> On 11/25/2014 11:51 PM, Pekka Paalanen wrote:
>>
>>> What \comment-line command are you looking for?
>>>
>>> I see you reformatted
>>>
>>>>>> - * wl_list_insert(&foo_list, &item1.link);   \comment{Pushes item1 at the head}
>>>
>>> but I assume you mean something else?
>>
>> No I meant that. I thought somebody had made the comment command to
>> produce "/* text */". Apparently however this is a holdover from javadoc
>> or something and doxygen does not do it.
>
> Sorry?
>
> doc/doxygen/wayland.doxygen.in has:
> ALIASES                += comment{1}="/* \1 *<!-- -->/"
>
> What's wrong with that?
>
>> I did some web searching, and everybody says the only way to do a
>> comment is to use a different comment style that can be nested. Since
>> C-style comments don't nest you have to use something else if the
>> doxygen comment is C-style. The doxygen code tag appears to make it
>> entirely literal, the only thing it recognizes is \endcode.
>>
>> Not sure if it would be acceptable to use C++ comments in Wayland
>> source, but that would be a solution. It was how I got around this
>> problem before.
>>
>> Another solution is to get Doxygen to produce code-like output but where
>> commands can be interpreted. Using <tt> and replacing every space with
>> <sp/> and every newline with <br/> works but is really ugly.
>>
>
> FWIW, with the Doxygen version I have, that \comment{foo} did
> produce /* foo */ in the output, just like one would expect, and it
> worked nicely where it was used.
>
> Our style is to use traditional C comments, not C++.
>
>
> Thanks,
> pq
>