Code::Blocks

Developer forums (C::B DEVELOPMENT STRICTLY!) => Development => Topic started by: ollydbg on February 13, 2012, 05:58:23 am

Title: comment style question
Post by: ollydbg on February 13, 2012, 05:58:23 am
I see many comment looks like in cbeditor.h
Code: [Select]
        /** 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>
          */

But the doxygen suggest like this:
Doxygen (http://www.stack.nl/~dimitri/doxygen/docblocks.html), the second line has different alignment.
Code: [Select]
/**
 * ... text ...
 */

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

Thanks.
Title: Re: comment style question
Post by: MortenMacFly on February 13, 2012, 07:18:22 am
So, the question is: which one should I use in the feature?
Thanks.
This one:
Code: [Select]
/** Short description
 *
 * Long description
 */
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: [Select]
/**
 * \brief Short description
 * Long description
 */
Title: Re: comment style question
Post by: ollydbg on February 13, 2012, 07:22:17 am
@morten, thanks for the reply. but my original question is:

Code: [Select]
/**
  *
  */

or

Code: [Select]
/**
 *
 */

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. :)
Title: Re: comment style question
Post by: MortenMacFly on February 13, 2012, 07:35:13 am
You see the vertical "*" alignment.
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.
Title: Re: comment style question
Post by: ollydbg on February 13, 2012, 09:43:21 am
What does the doxygen/CC plugin generate by default? Maybe that's the format we should choose.
I just test them, and both use the format:

Code: [Select]
/**
 *
 */

So, I will stick on this style.