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

[Pekka Paalanen]

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