Doxygen and Visual Studio

Doxygen is a tool for generating documentation from annotated source code. Originally created specifically for C++, it now also supports C, Objective-C, C#, PHP, Java, Python, IDL, Fortran, VHDL, Tcl, and D. Output formats include HTML, Latex, RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. Although developed in OS X and Linux, there is also an MS Windows executable.

This post will not discuss how to document your source code for use with Doxygen, nor will it list the advantages and disadvantages of using Doxygen. You will have to decide if Doxygen is the right tool for you. You should see the Doxygen website for that. This post will simply show how to use Doxygen with Visual Studio.

There are no extensions for integrating Doxygen with Visual Studio. However, Doxygen, and Doxywizard, a wizard-based executable for creating the configuration file for use with Doxygen, are command line executables which can easily be run from the Visual Studio Tools menu. Adding Doxygen and Doxywizard to the Tools menu is done as follows. The instructions work for both Visual Studio 2015 and Visual Studio 2017.

  1. Download and install the latest Doxygen Windows binary.
  2. Open the Visual Studio Tools dropdown menu and select External Tools…
  3. This opens the External Tools dialog:
    ExternalTools
    Click the Add button. The dialog changes to this:
    AddExternalTool
  4. Change the Title to Doxygen, the command to point to the Doxygen executable (C:\Program Files\doxygen\bin\doxygen.exe on my computer), the arguments to $(ProjectDir)\Doxyfile, and initial directory to $(ProjectDir). Check the Use Output window checkbox. The lower portion of the dialog box will look like this:
    AddDoxygen
    $(ProjectDir) is the macro in Visual Studio that points to the project directory (the directory that contains the project’s vcxproj file).
  5. Click the Apply button to add the Doxygen menu item to the Tools menu.
  6. Click the Add button.
  7. Enter DoxyWizard as the Title, the location of the doxywizard executable  as the Command (e.g. C:\Program Files\doxygen\bin\doxywizard.exe), leave Arguments blank, and $(ProjectDir) as initial directory. Leave all checkboxes unchecked.
  8. Click the OK button to add the DoxyWizard menu item and close the dialog box.

The first time you use Doxygen with a project, select the Tools -> DoxyWizard menu item to open the DoxyWizard dialog, shown here:
DoxyWizardDialog

  1. Step 1: Set the working directory to be the $(ProjectDir) directory. That is the directory containing the project’s vcxproj file.
  2. Step2: Use the Wizard and/or Expert tabs to set the configuration values.
  3. Select the Run tab and then Run doxygen.
  4. If you wish, go back and change the various configuration values.
  5. Once you are satisfied with the values you have set, close the dialog. This will display the Unsaved changes message box. Click Save to save the configuration. Select the directory that contains the project’s vcxproj file. This will ensure that the configuration file is found when you run Doxygen.

You should only run DoxyWizard once for each project that you are documenting. For each subsequent document generation, use Tools -> Doxygen. Provided you saved the configuration file in the correct location, Doxygen will run correctly, saving its generated documentation to the specified directory, and sending its output to the Visual Studio Output window.

 

Advertisements

4 thoughts on “Doxygen and Visual Studio

    • 1. This morning I downloaded the DoxyPress Windows setup program. When I executed it, Windows SmartScreen displayed the following: Windows SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk.

      Overriding this warning, and starting the setup program, I get the message: The program cannot be installed in C:\Program Files\DoxyPress. Please enter a different path…

      I will post to the DoxyPress forum to see what the problem is before installing the program elsewhere.

      2. Doxygen is used by a number of open source projects. Because of potential incompatibilities between Doxygen and DoxyPress, it is still necessary use Doxygen to ensure that the documentation is generated correctly when providing patches for these projects.

      Like

      • Thanks for that info. At my work we use an old, custom hacked up version of doxygen and we are considering moving to doxypress but haven’t done any experiments.

        From the above messages, it sounds like you are using Windows 8/8.1/10? It seems that in their goal of preventing you from installing malware by accident, they’ve made it impossible to install this program as the authors intended it. When I ran the install on Windows 7 I got the same message about not being able to install into C:\Program Files\Doxypress. Running the installer as administrator eliminated this problem. This just seems to be a bug in their installer; it should be authored in such a way that Windows asks you to elevate permissions and then allows you to install into the proper location.

        I’m not sure what the incompatibilities are that you mention. If you’re trying to contribute documentation fixes to some other project that uses doxygen, then yes, you’ll have to use that. If you’re documenting your own project and starting from nothing, then I would recommend doxypress from what I know about it. Doxygen has real problems parsing modern C++ code and doxypress uses libclang for parsing, which should make it standards compliant.

        Like

      • legalize, for some reason WordPress does not allow me to reply to your reply of my last post, so I have to do it here.

        Yes, I am using Windows 10.

        And yes, running the installer as Administrator does allow me to install DoxyPress into the Program Files directory. but it does not get rid of the Windows SmartScreen message the first time the installer is executed.

        At the time that I wrote the reply above, I was thinking that since Doxygen was forked to produce DoxyPress, DoxyPress may fix bugs or provide additional documentation choices that Doxygen does not. Thus, the statement was theoretical. Since then, I have found one such case:
        Assume you document an enum (or enum class) as follows:
        enum AnEnumClass {
        value1, ///< Line 1 of value1
        ///<
        ///< Line 2 of value1
        value2
        };

        In the generated documentation, Doxygen provides the following description for value1:
        "Line 2 of value 1
        Line 1 of value1"

        but with DoxyPress, the generated description is:
        "Line 1 of value 1
        Line 2 of value 1"

        So, DoxyPress produces different output than Doxygen in this case.
        Hence my comment about using Doxygen when contributing to an open source project that uses Doxygen for its documentation and not assuming that if it looks correct in DoxyPress, then it will look correct in Doxygen.

        Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s