Author Topic: Doxygen Editor?  (Read 17380 times)

JakeMontgomery

  • Community Member
  • Posts: 78
  • Hero Points: 8
Doxygen Editor?
« on: December 26, 2007, 06:05:22 pm »
I justed started a project that uses Doxygen and I am a bit confused ... it looks like SE now supports Doxygen as far as creating a skeleton header when typing /*! above a function - it uses the proper \param style.  However, when I try to use the GUI comment editor to edit them, it launches the Javadoc editor window, which seems to not recognize the \param style, and instead mangles my comment block back to a Javadoc style, adding a whole new set of @param lines.

So is there a comment editor in SE that supports Doxygen, or some way to get the Javadoc editor to use \param style?
(The nifty DocComment section in  Extension Options only seems to effect the creation of the skeleton header, not the comment editor.)

I am using 12.0.3

Any help appreciated.

ScottW, VP of Dev

  • Senior Community Member
  • Posts: 1471
  • Hero Points: 64
Re: Doxygen Editor?
« Reply #1 on: December 27, 2007, 10:22:02 pm »
Yes, I believe the comment editor is only for Javadoc. Frankly, we haven't really been keeping this up to date. Our approach has been to do more to better support editing comments in place. Comment Wrapping goes a long way in that direction. We believe this will always be a faster approach and allow greater flexibility than trying to build an all-encompassing GUI comment editor. SlickEdit 2008 is planned to include new capabilities to customize the comment templates that are inserted when you add a new doc comment, allowing for greater personalization.

Bottom line, we're not planning any enhancements to the GUI Comment Editor. If you think this is the wrong choice, please let me know so we can reconsider. 

Thanks.

JakeMontgomery

  • Community Member
  • Posts: 78
  • Hero Points: 8
Re: Doxygen Editor?
« Reply #2 on: December 28, 2007, 05:51:39 pm »
I guess I see the point about the GUI editor. I like and use it (when I am on a project that uses JavaDoc or XML comments), but it has always had a lot of annoying little details - it is usually not flexible enough to fit the exact documentation standards of the particular code base I am working on.  I see how this would be a never ending battle to make it suit everyones needs.  One thing that was nice about it, was the ability to go from function to function within the GUI comment editor.

Templates for initial in place comments would be nice.

I still have one big problem with Doxygen comments though.  The tagging system does not seem to recognize the items in them.  If I use @param (Javadoc style) then I get a nicely formatted comment when using things like codehelp_complete etc.  When I use the Doxygen style \param, the taging system seems to huge give me one long function level comment without line breaks, apparently not recognizing that \param means the same as @param.  This is not a show stopper, but it definitely makes Doxygen a second class citizen.

Thanks for all your help ... SE is still the best (just not for Doxygen).

gary_ash

  • Guest
Re: Doxygen Editor?
« Reply #3 on: December 28, 2007, 10:12:25 pm »
You could try my comment package at http://www.wideopenwest.com/~gary_ash/GenComment.htm
I haved created Doxygen templates for it that worked well enough for the company I was working for that used Doxygen

gb

spence

  • Community Member
  • Posts: 17
  • Hero Points: 2
Re: Doxygen Editor?
« Reply #4 on: January 23, 2008, 07:13:35 pm »
I too would like to see a Doxygen Editor a la the JavaDoc editor. I've always used the JavaDoc editor in the past and I've become very used to it, but now I'm working on a project that uses Doxygen and I miss the corresponding feature.

Thanks
--Spence

JakeMontgomery

  • Community Member
  • Posts: 78
  • Hero Points: 8
Patch allows Doxygen \ style in Tagging System
« Reply #5 on: February 07, 2008, 02:22:48 pm »
By the way, I really wanted the ability for the tagging system to be able to read the doxygen style comments with the \param instead of @param, so I could get all the cool features that come with that - like nicely formatted comments in the preview and with codehelp_complete, etc.   So I wrote a "hotfix" that does that.  I know that overriding built in SE functions is dangerous, and one must always be aware of them when updating or applying real hotfixes.  In any case, my code is able to determine what type of symbol is being used and so it seems to still work with \param style comment blocks, as well as @param style comment blocks. 

If anyone is interested I can post the "fix".

hs2

  • Senior Community Member
  • Posts: 2725
  • Hero Points: 280
Re: Doxygen Editor?
« Reply #6 on: February 07, 2008, 02:40:13 pm »
Since I've to deal with both comment styles I'd be very interested in the fix.
I'm also aware of the consequences of patching product macros.
Thanks in advance, HS2

JakeMontgomery

  • Community Member
  • Posts: 78
  • Hero Points: 8
Re: Doxygen Editor?
« Reply #7 on: February 07, 2008, 11:29:55 pm »
Ok, so attached is the file that mods the Tagging system to recognize doxygen style \ tags instead of @ tags.  The core of the system is an override of the system function _parseJavadocComment.  Most of the body is the same, with the needed mods. Let me say now, overriding SE system functions is DANGEROUS, so use at your own risk, and be aware of how this might effect future updates and hotfixes.  Also, let me say that I did this as a "need now" item in my very sparse free time, so it is not necessarily "cleaned up" for show.

With the new module installed, you should get automatic detection of the comment tag style.  This is based on the first type of tag detected in any one comment block, so feel free to mix and match within one file, but not within the same comment block.  There is also a global variable jrm_use_doxygen that can be used to turn off the auto detection, and more or less go back to the built in system. 

There are also a couple of other, not totally related things in here.  First off, the HTML conversion for comments totally ignores line breaks - I found that sometimes hard to read, so there is a bit in there that makes two consecutive line breaks into an actual line break in the resulting xml.   We also use the \brief tag a lot at the beginning of the comment, but the xml stuff treats that as a separate section from the main description, so it ends up far down the documentation.  I like seeing that first, so if the first tag is \brief, then that line is also treated as part of the main description.  Finally, in some cases the shipping parser was messing up if there was text on the same line as the opening of the comment, so the following code:

Code: [Select]
/** Main Description starts here
 *
 *  @param foo Describes foo
 *  @return TRUE always
 */
int fobar(int foo);

Would result in the parser not finding the param and return, but rather lumping it all into the description, so you would see the doc as:

Code: [Select]
Main Description starts here @param foo Describes foo @return TRUE always

There were a lot of such comment blocks in existing code, so there is a fix for that as well.

To install this, copy the attached file to your system - I put it in my "My Documents\My SlickEdit Config\12.0.3" folder (not sure if that is the ideal place, but it works.)  Then go to the "Macro->Load Module" menu item and load the file.  You should be good to go.

Good luck.

hs2

  • Senior Community Member
  • Posts: 2725
  • Hero Points: 280
Re: Doxygen Editor?
« Reply #8 on: February 08, 2008, 12:48:09 am »
Thanks a lot Jake and get a HP !
Also your additional changes sound great. I was cluttering my comment blocks with
 tags to improve readabilty.
This in turn makes it hard to read them in the source module.
I'm looking forward to give it a try asap.
Thanks again, HS2

JakeMontgomery

  • Community Member
  • Posts: 78
  • Hero Points: 8
Off Topic
« Reply #9 on: February 11, 2008, 03:37:52 pm »
Thanks a lot Jake and get a HP !

Thanks.

Off topic, but what does HP stand for?  (I usually figure this stuff out myself or with google, but no help there.)

hs2

  • Senior Community Member
  • Posts: 2725
  • Hero Points: 280
Re: Doxygen Editor?
« Reply #10 on: February 11, 2008, 03:53:57 pm »
HP == Hero Point for you :) - HS2

MRawlings

  • Community Member
  • Posts: 26
  • Hero Points: 2
Re: Doxygen Editor?
« Reply #11 on: June 11, 2008, 10:49:11 am »
Jake,

I hope you are still listening...

I spent some of yesterday trying to figure out why my Doxygen tags weren't being recognised by your updates and think I understand what is happening, I just don't know why or what I can do about it?

The following style of comments are recognised
Code: [Select]
/*!
** \brief short-desc
**
**        Longer Description
**
** \param[in]    p1    p1 descriptions
**
** \return             I hope so
*/

whilst this is not

Code: [Select]
/*!
**\brief short-desc
**
**        Longer Description
**
**\param[in]    p1    p1 descriptions
**
**\return             I hope so
*/


The only difference being the space, or lack thereof, before the backslash.

From following your extended code I don't think this happens because of your support, I think it is the member_msg which is passed into your code.

From your exploration of this area do you have any pointers for where I should look next?

Thanks,

Mark

JakeMontgomery

  • Community Member
  • Posts: 78
  • Hero Points: 8
Re: Doxygen Editor?
« Reply #12 on: June 11, 2008, 02:14:07 pm »
The only difference being the space, or lack thereof, before the backslash.
From following your extended code I don't think this happens because of your support, I think it is the member_msg which is passed into your code.
From your exploration of this area do you have any pointers for where I should look next?

Indeed, a quick test reveals that the  member_msg   going into _parseJavadocComment already has the \ striped when
Code: [Select]
/*\param is used instead of
Code: [Select]
/* \param

This also goes for the member_msg parameter passed to the _make_html_comments function that calls _parseJavadocComment.  Whatever code is originally parsing the comments doe s not strip the "@" from "/*@".

Unfortunately I am very busy at the moment and do not have the time to trace it back, but you would look at calls to _make_html_comments and start tracing back until you figured out where the original "pre-parsing" was occurring, then see if there was a reasonably safe way to fix it. (Once again, I must mention that modifying SE system functions is DANGEROUS.)

If you find a fix, please let us all know.

MRawlings

  • Community Member
  • Posts: 26
  • Hero Points: 2
Re: Doxygen Editor?
« Reply #13 on: June 13, 2008, 01:07:45 pm »
Completely dis-regarding Jake's warning I set about some more investigation and slight hacking.


In function _parse_multiline_comments

I have modified lines that started with

Code: [Select]
      // Support no space between * and @
to now be

     
Code: [Select]
// Support no space between * and @
      // MAR or * and \
      // MAR or allow **@ or **\
      //say('j='j);
      //say('prefix='prefix); // MAR
      if((prefix == '*@') || (prefix == '*\')) {
prefix = '*';
j = 3;
      } else if ((prefix == '**@') || (prefix == '**\')) {
prefix = '*';
j = 3;
      }

This at least no recognises my style of comments and allows your support to work as expected Jake.

I'll look at tidying this up and presenting it as a packaged solution.

Mark

MRawlings

  • Community Member
  • Posts: 26
  • Hero Points: 2
Re: Doxygen Editor?
« Reply #14 on: June 13, 2008, 04:44:46 pm »
This is for my records really.
I typically also
Code: [Select]
/param[in]  inputParam desc
/param[out]  outputParam desc

So I think my next task would be to make the HTML formatting understand that [in] or [out] or [in,out] at the start of the stored param data is not the parameterName, but that in these cases the parameterName is the word after the bracketed string, and that whole line should be somehow formatted subtly differently.

This is in make_html_comments as you suggest Jake.

Mark