c++visual-studio-2012intellisensedoxygenvisual-assist

Visual Studio 2012 IntelliSense with Visual Assist X and Doxygen


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:

IntelliSense

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

Hover ToolTip

while the mentioned IntelliSense yields

enter image description here

however moving the Doxygen style comment into the header has a strange result

enter image description here

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)


Solution

  • The only simple (but ugly way) I see is to add some preprocessor directives to make Visual Studio ignore it like

    #if 0
    /*! your comment
    */
    #endif
    

    You may want to add some stuff after the #endif so you can easily remove it with research and replace without removing the ones you need. At least in VS2013 it ignores pretty well the #if 0 blocks. With this you should be able to leave them in the same file so it's less of a pain.