Developer forums (C::B DEVELOPMENT STRICTLY!) > Development

comment style question

(1/1)

ollydbg:
I see many comment looks like in cbeditor.h

--- Code: ---        /** cbEditor constructor.
          * @param parent the parent notebook - you should use EditorManager::Get()
          * @param filename the filename to open. If filename is empty, it creates a
          * new, empty, editor.
          * @param theme the initial colour set to use\n
          * <em>Note: you cannot create a cbEditor object directly. Instead
          * use EditorManager's methods to do it...</em>
          */

--- End code ---

But the doxygen suggest like this:
Doxygen, the second line has different alignment.

--- Code: ---/**
 * ... text ...
 */

--- End code ---

So, the question is: which one should I use in the feature?

Thanks.

MortenMacFly:

--- Quote from: ollydbg on February 13, 2012, 05:58:23 am ---So, the question is: which one should I use in the feature?
Thanks.

--- End quote ---
This one:

--- Code: ---/** Short description
 *
 * Long description
 */

--- End code ---
The first line has a special character. It declares the short description shown in the documentation. Inspect the doxygen manual for more information...

If unsure, you can also do something like this:

--- Code: ---/**
 * \brief Short description
 * Long description
 */

--- End code ---

ollydbg:
@morten, thanks for the reply. but my original question is:


--- Code: ---/**
  *
  */

--- End code ---

or


--- Code: ---/**
 *
 */

--- End code ---

You see the vertical "*" alignment.

PS: If you suggest using the second one, than there are vertical "*" alignment in C::B's comments should be changed. :)

MortenMacFly:

--- Quote from: ollydbg on February 13, 2012, 07:22:17 am ---You see the vertical "*" alignment.

--- End quote ---
I think as long as it is consistent in a compilation unit (header file) its fine. The result will be the same if you compile the documentation, so it doesn't really matter in the code. What does the doxygen/CC plugin generate by default? Maybe that's the format we should choose.

ollydbg:

--- Quote from: MortenMacFly on February 13, 2012, 07:35:13 am ---What does the doxygen/CC plugin generate by default? Maybe that's the format we should choose.

--- End quote ---
I just test them, and both use the format:


--- Code: ---/**
 *
 */

--- End code ---

So, I will stick on this style.

Navigation

[0] Message Index