Author Topic: comment style question  (Read 5888 times)

Offline ollydbg

  • Developer
  • Lives here!
  • *****
  • Posts: 5910
  • OpenCV and Robotics
    • Chinese OpenCV forum moderator
comment style question
« 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, the second line has different alignment.
Code
/**
 * ... text ...
 */

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

Thanks.
If some piece of memory should be reused, turn them to variables (or const variables).
If some piece of operations should be reused, turn them to functions.
If they happened together, then turn them to classes.

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9694
Re: comment style question
« Reply #1 on: February 13, 2012, 07:18:22 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
 */
Compiler logging: Settings->Compiler & Debugger->tab "Other"->Compiler logging="Full command line"
C::B Manual: https://www.codeblocks.org/docs/main_codeblocks_en.html
C::B FAQ: https://wiki.codeblocks.org/index.php?title=FAQ

Offline ollydbg

  • Developer
  • Lives here!
  • *****
  • Posts: 5910
  • OpenCV and Robotics
    • Chinese OpenCV forum moderator
Re: comment style question
« Reply #2 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. :)
« Last Edit: February 13, 2012, 07:24:17 am by ollydbg »
If some piece of memory should be reused, turn them to variables (or const variables).
If some piece of operations should be reused, turn them to functions.
If they happened together, then turn them to classes.

Offline MortenMacFly

  • Administrator
  • Lives here!
  • *****
  • Posts: 9694
Re: comment style question
« Reply #3 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.
Compiler logging: Settings->Compiler & Debugger->tab "Other"->Compiler logging="Full command line"
C::B Manual: https://www.codeblocks.org/docs/main_codeblocks_en.html
C::B FAQ: https://wiki.codeblocks.org/index.php?title=FAQ

Offline ollydbg

  • Developer
  • Lives here!
  • *****
  • Posts: 5910
  • OpenCV and Robotics
    • Chinese OpenCV forum moderator
Re: comment style question
« Reply #4 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
/** 
 *
 */

So, I will stick on this style.
If some piece of memory should be reused, turn them to variables (or const variables).
If some piece of operations should be reused, turn them to functions.
If they happened together, then turn them to classes.