Code::Blocks Forums

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

        /** 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

/**
 * ... 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

Quote from: ollydbg on February 13, 2012, 05:58:23 am

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

This one:

Code

/** 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

/**
 * \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

/** 
  *
  */

or

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

Title: Re: comment style question
Post by: MortenMacFly on February 13, 2012, 07:35:13 am

Quote from: ollydbg on February 13, 2012, 07:22:17 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

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.

I just test them, and both use the format:

Code

/** 
 *
 */

So, I will stick on this style.