Doxygen style guide

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Doxygen style guide

siko1056
Dear maintainers,

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

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

My two pence,
Kai


[1]: http://wiki.octave.org/C%2B%2B_style_guide#Doxygen_Style_Guide
[2]:
https://hg.savannah.gnu.org/hgweb/octave/file/1c2f34a2c60d/libgui/src/qtinfo/texinfo-parser.h#l96
[3]:
https://hg.savannah.gnu.org/hgweb/octave/file/1c2f34a2c60d/libinterp/octave-value/ov-classdef.h#l888
[4]: https://www.stack.nl/~dimitri/doxygen/manual/markdown.html
[5]: https://www.stack.nl/~dimitri/doxygen/manual/commands.html



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

Reply | Threaded
Open this post in threaded view
|

Re: Doxygen style guide

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

Reply | Threaded
Open this post in threaded view
|

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

Reply | Threaded
Open this post in threaded view
|

Re: Doxygen style guide

Rik-4
In reply to this post by siko1056
On 09/22/2017 09:00 AM, [hidden email] wrote:
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.

Very easy to uncover a raft of different opinions here.  I like the line above, but not the line below.  For me, the line above is the same as would be present for any division between code blocks.  But if I a have a convention that a blank line creates divisions then I don't want such a division at the bottom of the line of comments.  Instead, I want the comments cuddled with the code to which they apply.

Also, I never have any practical problem distinguishing code from comments because, even super old school text interfaces like Vim, have syntax highlighting;  The comments are in one color and the code is in another, done.

--Rik