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)
Doxygen comments repeated and/or truncated badly
Posted - Apr 03 2013 : 10:14:42 AM
