Whole Tomato Software Forums
Whole Tomato Software Forums
Main Site | Profile | Register | Active Topics | Members | Search | FAQ
User name:
Password:
Save Password
Forgot your password?

 All Forums
 Visual Assist
 Technical Support
 Doxygen comments repeated and/or truncated badly
 New Topic  Reply to Topic
 Printer Friendly
Author Previous Topic Topic Next Topic  

qwerty
New Member

2 Posts

Posted - Apr 03 2013 :  10:14:42 AM  Show Profile  Reply with Quote
I used to write simple comments into my header files in the style of
// Returns a new string in which all occurrences of a specified string in the
// current instance are replaced with another specified string.
// - strSubject: The string to perform the replacement on.
// - strOldValue: The string to be replaced.
// - strNewValue: The string to replace all occurrences of strOldValue.
static RUNTIME_API String::type Replace
    (_In_       String::type  strSubject,
     _In_ const String::type& strOldValue,
     _In_ const String::type& strNewValue);

such that Visual Assist displays me exactly this comment:

Currently I am thinking about using Doxygen to create a documentation for the project, however I am struggling finding a documentation style which is correctly displayed in the ToolTips and can be parsed with Doxygen. First I was thinking about including Doxygen style comments in the *.cpp files such that I get only the header comments displayed. Therefore in my source file I have a comment like
/*!
 * Returns a new string in which all occurrences of a specified string in the
 * current instance are replaced with another specified string.
 *
 * \\param   strSubject  The string to perform the replacement on.
 * \\param   strOldValue The string to be replaced.
 * \\param   strNewValue The string to replace all occurrences of strOldValue.
 * 
 * \\return  A string that is equivalent to the current string except that all
 *          instances of strOldValue are replaced with strNewValue. If
 *          strOldValue is not found in the current instance, the method returns
 *          the current instance unchanged.
 */
String::type String::Replace
    (_In_       String::type  strSubject,
     _In_ const String::type& strOldValue,
     _In_ const String::type& strNewValue) { /* ... */ }

Surprisingly I get two different outputs when hovering this function or when getting Visual Assists "IntelliSense". Hovering the Replace yields

while the mentioned IntelliSense yields

however moving the Doxygen style comment into the header has a horrible result truncating comments

I would like to know whether you have suggestions how I can use Qt style doxygen comments but having IntelliSense display the appropriate tooltip (whichever it might be) and not display different ones based on how I invoke it? There has to be a way to unify this. (Alternatively I have to work as always and create separate documentary headers which only consist of doxygen comments - this way I won't have issues but would have redundant data)

feline
Whole Tomato Software

United Kingdom
17256 Posts

Posted - Apr 03 2013 :  12:24:11 PM  Show Profile  Reply with Quote
Are you working with VS2012? There is a known bug, where VA is adding comments to the tooltips even when you turn this option off in our options dialog:

case=73217

When this is fixed you will be able to turn off:

VA Options -> Advanced -> Display -> Display comments from source files when available

and only see the comment block once, not twice, in the tooltips.

zen is the art of being at one with the two'ness
Go to Top of Page

qwerty
New Member

2 Posts

Posted - Apr 03 2013 :  5:30:42 PM  Show Profile  Reply with Quote
Yeah I am using VS2012. What I really would suggest is that once Doxygen comments in the header files are recognized both during a mouse over of a member and live code completion - that is enter e.g.
String::Replace(
- the upper block is displayed only:


This obviously works partly but not as intended?
Go to Top of Page

feline
Whole Tomato Software

United Kingdom
17256 Posts

Posted - Apr 04 2013 :  2:01:24 PM  Show Profile  Reply with Quote
This is covered by case=73217, which is down as a high priority bug, so hopefully this will be fixed soon. Having the same comment block listed twice in the same tooltip is not what is supposed to be happening.

zen is the art of being at one with the two'ness
Go to Top of Page

sean
Whole Tomato Software

USA
2817 Posts

Posted - Apr 10 2013 :  9:18:49 PM  Show Profile  Reply with Quote
The next release of VA tries to make sure that it does not duplicate comments added to QuickInfo by VS2012 VC++ default intellisense.

Some things to note about the way VS2012 does comments:
The tooltip has a different comment if you over the declaration, the definition or the invocation of a method.
When you hover over the declaration, it will use the comment right there at the declaration.
When you hover over the definition, it will use the comment right there at the definition.
When you hover over a use (not the declaration or the definition), then it will use the comment at the definition.

VS2012 will ignore the declaration comment if the definition is separate from the declaration.
VS2012 will not display the comment above a definition if there is a blank line between the comment and the definition.
VS2012 removes comment delimiters from the tooltip (and may otherwise reformat the comment); when you see /* or // in the tooltip, the content came from VA.
Go to Top of Page

support
Whole Tomato Software

5566 Posts

Posted - Apr 25 2013 :  2:33:39 PM  Show Profile  Reply with Quote
case=73217 is fixed in build 1936
Go to Top of Page
  Previous Topic Topic Next Topic  
 New Topic  Reply to Topic
 Printer Friendly
Jump To:
© 2019 Whole Tomato Software, LLC Go To Top Of Page
Snitz Forums 2000