Re: Doxygen style guide

[John W. Eaton]

On 09/22/2017 05:29 AM, siko1056 wrote:

> In the wiki a new Doxygen style guide appeared [1].  Did I miss a discussion
> about it, or is it just a recommended standard?  We don't have that much
> comments at the moment, but recently I added some [2] that would totally
> violate [1] ;-) The standard found first application in [3].

We had some discussion on IRC.  Nothing is final, but it seemed a good 
idea to start defining some style guide as we have quite a mixture of 
styles currently.

> Personally, I would add two items:
>
> 1. Only Markdown [4] and Doxygen commands [5] should be allowed, especially
> not HTML (it just bloats up things with tags).

I agree with that.  Keep it simple.

> 2. No blank lines between the Doxygen comment and the function definition,
> to make the assignment clear (if one blank line is above and below [3], it
> is not that clear if it belongs to the following definition).

I know this is a matter of personal preference, but I like the blank 
lines around large blocks of comments.  When there is no space, I think 
it can be harder to separate the code from the comments.  OTOH, maybe 
that is less true now that most things that display code do some kind of 
syntax highlighting.  OTTH, whether there is a blank line or not, 
Doxygen seems to know that these blocks of comments apply to the next 
function and it also seems fairly obvious to me.

jwe