Re: Doxygen style guide

[siko1056]

John W. Eaton wrote
> 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

Agree jwe, like all C/C++ code formatting, it is just a question of personal
taste.  I updated the guide's example to what I understand and try apply it
in the future as well.

Kai



--
Sent from: http://octave.1599824.n4.nabble.com/Octave-Maintainers-f1638794.html