Author Topic: C Function header comment expansion  (Read 7023 times)

jimbo333

  • Community Member
  • Posts: 58
  • Hero Points: 3
C Function header comment expansion
« on: June 04, 2008, 04:49:15 pm »
I am trying to setup comment expansion to match the function comment style we use.  There are a few things I can't figure out how to do:

1)  Put the function name in the comment, the variable %\c does not seem to work outside the function.

2)  Put the function prototype in the comment, like %\o, which has the same problem as above.

3)  Have a flag that is opposite of the %\v, which means is only included if NO return value is specified, so I can place a line with the word 'None', instead of just leaving it off.

4)  The parameter listing functions don't seem to work for K&R style function decelerations.

Here is an what I have setup so far, which works except for the issues above:

/* %\n - %\c */
**
** %\o
**
** %\c
** %\u
** Parameters: %\u
**   %\p - %\c
** %\v
** Returns: %\v
**   %\c%\v
**
** Global variables used:
**   %\c
*/


Here is an example of a function definition:

/* function - quick description */
**
** void function( param1 )
**
** A multi-line long description of the function. 
** Extra lines....
**
** Parameters:
**   param1 - Parameter description.
**
** Returns:
**   none
**
** Global variables used:
**   var1 - Sample global variable referenced.
*/

void function( param1 )
int param1;
{
}




Clark

  • SlickEdit Team Member
  • Senior Community Member
  • *
  • Posts: 5177
  • Hero Points: 429
Re: C Function header comment expansion
« Reply #1 on: June 04, 2008, 08:19:07 pm »
I checked in a partial fix for 1) and 2) (works for functions only).  My fix also fixes problem 4).  It will be available in the 13.0.1 update.

jimbo333

  • Community Member
  • Posts: 58
  • Hero Points: 3
Re: C Function header comment expansion
« Reply #2 on: June 04, 2008, 09:29:24 pm »
Thanks for the quick response, I will await the update for items 1, 2, and 4.  As for Item 3, I was able to modify alias.e to make it work.
I added the ability to put a '!' character after the U or V, to mean the invert the result.  I could probably implement this as a Macro that is called, but maybe this change could be added to 13.0.1 instead  :)

I modified the two cases, in version 13.0.0, lines 1066+, added about 10 lines.

I am not sure what the policy is on posting modified code snip-its from included Slickedit macro files, so I have not included it here, but I can post the change if it would be useful and allowed.

Clark

  • SlickEdit Team Member
  • Senior Community Member
  • *
  • Posts: 5177
  • Hero Points: 429
Re: C Function header comment expansion
« Reply #3 on: June 05, 2008, 03:09:44 pm »
Go ahead an post your change here.  I'll take a look at it.  I can't gaurentee I'll add it but I'm definitely thinking about it.

jimbo333

  • Community Member
  • Posts: 58
  • Hero Points: 3
Re: C Function header comment expansion
« Reply #4 on: June 05, 2008, 03:30:20 pm »
Thanks!  I had to post the code in an attachment, I was getting an error when trying to post it in the message body, it must have some special character sequence that causes the post to fail..  Here is the comment-header that I am now using, which seems to work great:


/*%\n - %\c
**
** %\o
**
** %\c
**
** Parameters:
**   none%\u!
**   %\p - %\c
**
** Returns:
**   none%\v!
**   %\c%\v
**
** Global variables used:
**   %\c
*/


chrisant

  • Senior Community Member
  • Posts: 1410
  • Hero Points: 131
Re: C Function header comment expansion
« Reply #5 on: June 05, 2008, 07:33:52 pm »
If you switch it so the ! goes between the % and the letter, it will have a lower chance of falsely getting interpreted.  Not that there's much of a chance to begin with, but in principle it would make parsing more robust.

Clark

  • SlickEdit Team Member
  • Senior Community Member
  • *
  • Posts: 5177
  • Hero Points: 429
Re: C Function header comment expansion
« Reply #6 on: June 05, 2008, 08:03:05 pm »
We are going to go with %\vn and %\un instead of %\v! and %\u!.  I added a new %() escape sequence which can be used as a delimeter to handle ambiguities.  %\v%()n separates the v from the n so the %\v is not mistakenly interpreted as %\vn if the user did not want it.  The down side is that this can potentially brake existing aliases (very unlikely though).  It will be recommended that %() be used to separate trailing alias escape letters from other letters.  Don't write %\dx. write %\d%\()x letters. 

It may be better for the code to require the separator to avoid any potential ambiguities (i.e parse %\identifier and not just %\letter).  This would break more existing aliases but once those aliases were fixed, there would be no possibility for alias compatibility issues.

jimbo333

  • Community Member
  • Posts: 58
  • Hero Points: 3
Re: C Function header comment expansion
« Reply #7 on: June 05, 2008, 08:06:34 pm »
I had thought about that when I wrote the change, but here were my arguments against that:

1)  I wanted to keep the change simple to implement, without the possibly affecting other tokens.

2)  It is more difficult to change the length of the identifier, it uses an expression that expects one digit after the %\, %\([0-9a-zA-Z_]#\), which is easy to change, but then later assumes the token is 3 digits.  The length would now have to be calculated (or assumed 4 digits if a ! is identified in the third byte).

3)  These expressions always effect the entire line, thus should probably appear at the end of the line, there should be no conflict.  However, I could see perhaps using this same token for other parameters that don't effect the entire line.

4)  Other tokens do have parameters, like %\X, which is done following the token, like I implemented.

I do think you brought up a valid point, so I will implement using your method if Clark/Slickedit agrees :)

EDIT: I see Clark beat me to the punch, the implementation he mentioned sounds good to me.
« Last Edit: June 05, 2008, 08:09:11 pm by jimbo333 »