Doxygen and XML Doc Comment support

Nick Uhlenhuth

Nick

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
Image quadraticXMLgen
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:

Image documentationOptions

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:

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.

Image QuadraticDoxygen

Tooltip Display

Documentation artifacts will now appear in Quick Info, Member List, and Parameter Help tooltips:

Image 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.

7 comments

Leave a comment

  • Avatar
    Christoph Hausner

    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).

    • Avatar
      Kalle Niemitalo

      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.

      • Avatar
        Yupeng Zhang

        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.

  • Avatar
    Victor Derks

    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?

  • Avatar
    mucki private

    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 ///)

    • Avatar
      Greg Smith

      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.