Hi, Visual Assist has a feature to show documentation comments of a member/function when using it, which is very helpful, but it doesn't support comments after members. In Doxygen, we can document members by usually special comment blocks that look like this:
/// This is a random function void blah();
But it's also possible to document after the member:
void blah(); ///< This is a random function
Visual Assist doesn't seem to be able to recognize this and would instead use the comments above it. This leads to situation like this:
I know this is a slippery slope to parsing any kinds of generic comment structure, but seems like this is a matter of being able to parse comments before or after a member. If we really want to be generic and not having to be doxygen specific maybe an option field for us to fill in what the beginning tag for "comments after memebers" would look like? I can just manually fill in the "///<" and related tags manually.
We are trying to avoid getting into parsing comments, since they are free text.
Out of interest is there some reason why you are putting the comments after the members? I have never seen this done before, and it seems like a rather confusing thing to do.
So the justification for this style is that it's easier to read (once you get used to it) as it flows better. Usually when we read a function we first care about the function name/signature, then the description of what it does. When we have a long description it sometimes devolves to this:
/// RandomFuncName /// /// This is a random description void RandomFuncName(int a, int b);
Instead of this we can just have the following:
void RandomFuncName(int a, int b); ///< This is a random description
The real reason is that our lead engineer likes this style and a lot of our core code is written like that...
I'm not really hoping for any special parsing, but it would be nice to be able to specify what kind of comment prefix (in this case "///<") would mean it's documenting the function above instead of below.
I do agree it's relatively uncommon even though doxygen supports it.
Unfortunately this is not something we are going to try and support. Working out how to match comments to variables / functions is already tricky, and this would add quite a lot of complexity for very little benefit.
Doxygen gets to make certain assumptions about the comments, assumptions that VA cannot make.
Feature: Support for header comments AFTER member
Posted - Aug 18 2010 : 9:33:28 PM
