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

[Pekka Paalanen]

On Thu, 27 Nov 2014 13:00:07 -0800
Bill Spitzak <spitzak at gmail.com> wrote:

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

Yeah, going back to ~~~ sounds good.

Doxygen 1.8.0 was released in Feb 2012. I'm not sure about making it a
hard requirement if one is building the docs, but we could at least warn
about an older version.


Thanks,
pq