Я использовал для написания простых комментариев в мои заголовочные файлы в стиле
// 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);
такой, что Visual Assist отображает мне именно этот комментарий:
В настоящее время я думаю об использовании Doxygen для создания документации для проекта, однако я изо всех сил пытаюсь найти стиль документации, который правильно отображается в подсказках и может быть проанализирован с помощью Doxygen. Сначала я думал о включении комментариев в стиле Doxygen в файлы * .cpp, чтобы отображались только комментарии заголовка. Поэтому в моем исходном файле у меня есть комментарий как
/*!
* 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) { /* ... */ }
Удивительно, но я получаю два разных вывода при наведении курсора на эту функцию или при получении визуальных помощников «IntelliSense». Зависание Replace
доходность
в то время как упомянутый IntelliSense дает
Однако перемещение комментария в стиле Doxygen в заголовок имеет странный результат.
Я хотел бы знать, есть ли у вас предложения, как я могу использовать комментарии Doxygen в стиле Qt, но IntelliSense отображает соответствующие всплывающие подсказки (какие бы они ни были) и не отображает различные подсказки в зависимости от того, как я их вызываю? Должен быть способ объединить это. (В качестве альтернативы я должен работать как всегда и создавать отдельные заголовки документа, которые состоят только из комментариев doxygen — таким образом у меня не будет проблем, но у меня будут избыточные данные)
Единственный простой (но уродливый способ), который я вижу, — это добавить некоторые директивы препроцессора, чтобы Visual Studio игнорировал их как
#if 0
/*! your comment
*/
#endif
Возможно, вы захотите добавить некоторые вещи после #endif, чтобы вы могли легко удалить их с помощью исследования и заменить, не удаляя те, которые вам нужны. По крайней мере, в VS2013 он довольно хорошо игнорирует блоки #if 0.
При этом вы сможете оставить их в одном файле, чтобы не было проблем.
Других решений пока нет …