Author Topic: How to arrange comments in .c and .h files?  (Read 6701 times)

AlexBi

  • Junior Community Member
  • Posts: 4
  • Hero Points: 0
How to arrange comments in .c and .h files?
« on: August 29, 2006, 12:19:13 pm »
Is there any manual how to arrange comments in .c and .h files and where comments should be placed? I want all my structures, structures members, functions and so on to be commented and comments to be shown to me during usage. For example:

/* Here is type description */
typedef struct {
 int fld1;   // here is description for fld1
 char fld2; // here is description for fld2
} my_type;

dunkers

  • Senior Community Member
  • Posts: 693
  • Hero Points: 28
Re: How to arrange comments in .c and .h files?
« Reply #1 on: August 29, 2006, 12:29:53 pm »
Oh boy! Stress testing the new forum :)

It's a very personal thing, but you might like to check out doxygen can generate documentation from your comments. If you use the style doxygen likes then you won't be going far wrong, in my opinion.

http://www.doxygen.org

As a bonus, SlickEdit understands Javadoc, which is one of the styles doxygen likes too.

AlexBi

  • Junior Community Member
  • Posts: 4
  • Hero Points: 0
Re: How to arrange comments in .c and .h files?
« Reply #2 on: August 29, 2006, 01:13:22 pm »
I have reread my previous post and find that it could be misapprehended. Sorry, English is not my native language. I just want to know what styles does SlickEdit understand?

dunkers

  • Senior Community Member
  • Posts: 693
  • Hero Points: 28
Re: How to arrange comments in .c and .h files?
« Reply #3 on: August 29, 2006, 02:26:20 pm »
No problem. It doesn't even affect my answer much!

SlickEdit understands any valid comment format for the purposes of syntax highlighting. However, it knows about Javadoc and will generate/update Javadoc style comments. For instance, if you had the following function:
Code: [Select]
int aFunc(int aValue, char *aString)
{
}

Place your cursor at the start of the function then right click and select "Edit Javadoc comment...". Fill in some details from the resultant dialog and you end up with something like this:
Code: [Select]
/**
 * A Javadoc comment demonstration
 *
 * @param aValue  Some integer value
 * @param aString A string pointer
 *
 * @return Returns an int
 */
int aFunc(int aValue, char *aString)
{
}

Er... I guess that can look a bit horrible to humans in its raw form, but feed the source through the aforementioned Doxygen and you get a very cool documentation with hotlinks and everything. In this context, SlickEdit understands that style of comment. If you go back and do select the "Edit Javadoc...." thing again you'll be editing the comment in a nice dialog rather than in its raw form.

Is that more along the lines of what you were after?

AlexBi

  • Junior Community Member
  • Posts: 4
  • Hero Points: 0
Re: How to arrange comments in .c and .h files?
« Reply #4 on: August 29, 2006, 03:38:25 pm »
Thanks for your replays. Raw form is not horrible for me and looks like what I want. :) Is JavaDoc the only form of comments understandable by SlickEdit? Is there description of all forms of comments understandable by SlickEdit?

dunkers

  • Senior Community Member
  • Posts: 693
  • Hero Points: 28
Re: How to arrange comments in .c and .h files?
« Reply #5 on: August 29, 2006, 04:28:22 pm »
I think a more knowlegeable person needs to answer that - I think it's just Javadoc, but there may be something else that's better hidden. Likewise, I think the assumption is that you'll already know about Javadoc if you want to use it.

ScottW, VP of Dev

  • Senior Community Member
  • Posts: 1471
  • Hero Points: 64
Re: How to arrange comments in .c and .h files?
« Reply #6 on: August 29, 2006, 08:52:12 pm »
Hmm...that's a hard one, a comprehensive list of comments we support. Sorry, I don't have one. Often, because our functionality is so broad, your best bet is to try it and see. Select Tools > Options > File Extension Setup and then select the Tagging tag. Put a check in "Show info for symbol under mouse". This will display a pop-up with the comment information we can pick up for the selected symbol. You can turn this off later if you don't like the option, but it is useful for testing.

In my attempts, I was able to get SlickEdit to pick up block comments and line comments for functions. If you comment both the header and the body, we'll combine them as best we can.

For variables, use line comments or block comments. You can place these above or on the same line.

We recommend the use of formatted comments, like Javadoc or Doxygen since these give us more information to use for formatting. By far, we provide more support for Javadoc than anything else. I like to use Javadoc for functions and line comments for variables. But you'll be able to quickly figure out what works for you.

--Scott