Doxygen and XML Doc Comment support
Nick Uhlenhuth
Whether you’re using Doxygen or XML Doc Comments, Visual Studio version 16.6 Preview 2 provides automatic comment stub generation as well as Quick Info, Parameter Help, and Member List tooltip support.
Stub Generation
By default, the stub generation is set to XML Doc Comments. The comment stub can be generated by typing a triple slash (///) or by using the documentation generation shortcut (Ctrl+/) above the function.
XML Doc Comment
Doxygen
To switch to Doxygen, type “Doxygen” in the Ctrl+Q search box, or go to Tools > Options > Text Editor > C/C++ > > General, and choose your preferred documentation style:
Once specified, you can generate the comment stub by typing the respective “///” or “/**” above a function, or by using the (Ctrl+/) shortcut.
You can also specify this documentation option on a per-folder or per-file basis via .editorconfig files with the corresponding setting:
vc_generate_documentation_comments = none
vc_generate_documentation_comments = xml
vc_generate_documentation_comments = doxygen_triple_slash
vc_generate_documentation_comments = doxygen_slash_star
To get started, you can have Visual Studio generate an .editorconfig file for you based on your existing setting for documentation by using the “Generate .editorconfig file from settings” button shown in the screenshot above.
Tooltip Display
Documentation artifacts will now appear in Quick Info, Member List, and Parameter Help tooltips:
Give us your feedback
Download Visual Studio 2019 version 16.6 Preview 2 today and give this new documentation support a try. We can be reached via the comments below, email (visualcpp@microsoft.com), and Twitter (@VisualC). The best way to file a bug or suggest a feature is via Developer Community.
Light
Dark
12 comments
C# had this for a long time, great to see it finally coming to C++, as well. This is a great time-saver and a good incentive to document your code base in Doxygen style as it now properly shows up in IntelliSense (whereas before, with unstructured comments, IntelliSense would often show comments with bad formatting).
Would be cool to have the STL headers annotated this way with information from docs.microsoft.com to see it directly in IntelliSense.
It is better to bring the information from docs.microsoft.com to IntelliSense in a different way, so it does not affect build times, can be translated to the developer’s language, and can be edited with no risk of accidentally modifying the code.
Having the ability to provide addition document other than header files will be also helpful for people document in the .cpp file.
Our company ask people to document in Doxygen in .cpp file instead of .h so that change documentation does not cause rebuild.
I like this feature, however some feedback\questions:
1. Is there guidance what to use in certain cases. For example should I use XmlDoc or Doxygen for cross platform development.
2. Is there an overview other IDEs (Visual Studio Code, etc. ) that can use this and which formats they support.
3. What is the guideline to put the documentation: in the .h file or the .cpp file?
4. The .editorconfig option is great, but as the option is called “vc_generate_documentation_comments” I can assume the VS is the only IDE that can use this editor option. Are there plans to make this in a more generic option that can be used by more code editors?
This is awesome, one less plugin I have to use! Just one feature request: we use a different style of doxygen comments (//! comment marker, \param command style). I would love if the config would allow me to directly specify how to format instead of just two hardcoded options (/** vs ///)
Yes Yes Yes…
Our house style is:
//! This is the brief function description
/*!
\param Arg1 The first parameter description.
\param Arg2 The next paramater…
…
\return The return value
*/
Which is a lot less horrible to look at than all the /// at the start of each line.
Please let us define our own templates.
This only works if I put the xml comments in the header file and not in the cpp file. Your example above implies it works when adding the xml comments to the cpp. Which is correct?
Thanks,
It’s a great news about support doxygen style comments.
Here is some questions about plans.
Would you plan to support:
1. special formatting features like LIST’s in parameter description?
2. documenting the structure/class members?
3. use special commands like \class, \struct, \enum and so on?
4. internal references through \see command?
Thanks.
This is a welcome addition, but unfortunately the tooltip display omits important information such as \throw and \remark, making it less useful than simply showing the raw comment accompanying the header declaration. It would also be nice if referencing via \see were supported; for example, if the entire description consists of a single \see directive, the documentation for the referenced symbol should be shown.
Two suggestions/requests:
1. This may already exist and I haven’t figured it out, but it would be great if we could include links to our in-house documentation instead of (or in addition to) the existing “Search online” link that is already included in the tool tip. We have all of our in-house libraries documented in a wiki and we would love to be able to get to it [almost] directly!
2. This one is kinda pie-in-the-sky, but it doesn’t hurt to ask, right? (smile) I think it would be awesome if the documentation files could be separate from the code. For example, as a new type of source file in the project (one that is not included in the executable build, but the only one included in the documentation build?) We have tried adding this type of documentation to our headers, but it actually tends to detract from “browsing” the header to look for a function whose name you cannot quite remember — all of the “noise” added by these comments eliminates the nice, clear lists of functions that our function declaration headers normally use.