When developing .NET applications, XML comments is a good way of documenting the code (looking back in 2015, my advice would be to not state the obvious, though).
If you are not familiar with documenting your C# code with XML comments, have a look at this page.
XML comments is just one way of documenting your work. Use these kind of comments for documenting classes and functions that you want to be made publicly available, and more expressive (since you can describe properties, attributes etc. as well). XML comments will be parsed by Visual Studio as well, and be used to provide you with IntelliSense for your own code.
Other ways of documenting your code, is to use plain text files (classic readmes), wikis etc. as well as common inline comments:
However, when you want to be able to automatically parse documentation from your .NET source code, XML comments is the way to, and this is how you do it:
Generate an XML file from XML comments
If you have documented your code with XML-comments, you can tell Visual Studio to export the documentation to a separate .xml file each time you build your project.
This is easily done under
If you enable .xml file extraction, Visual Studio will generate an .xml file each time you build your project. This file can then be parsed by various software, to generate documentation of various types, e.g. help files, HTML documentation etc.
However, if you want to expose the documentation for a wide audience, e.g. if you want to publish the api documentation for a framework or library, .xml files only takes you so far. If so, you are better off generating an HTML-based documentation directly from your source code instead.
Generate HTML documentation from XML comments
Previous versions of Visual Studio had built-in support for generating HTML-based documentation from C# code. However, I think Visual Studio 2003 was the last version to have it. Removing this support is rather strange, so let’s find a substitute!
To get started, first download, install and start Doxygen, then configure it like this:
- Enter project name and version - this will be used as page title
- Point out the source code root folder, which is where your source code is
- Check Scan recursively to make sure that all namespace folders are parsed
- Point out the documentation destination folder, which is where your HTML documentation will end up
- Instead of Documented Entities, select “All Entities” - this will also extract a nice namespace list
- Since we are extracting documentation for C#, select “Optimize for Java or C# output”
- Make sure that HTML is checked and choose the format you prefer (I like the frame/tree format, but this is just a matter of taste :)
- Latex, Man pages, RTF and XML are fully optional options, not described in this post
- Select “Use built-in class diagram generator”
- Uncheck “FULL_PATH_NAMES” to avoid displaying file paths in the documentation
- Check “EXTRACT_STATIC” to include static classes
- Click “Run doxygen” to generate the HTML documentation. When done, view the result by clicking “Show HTML output”.
If you are happy with the outcome, save the config for future use, so you don’t have to go through all the steps above each time.
When the HTML documentation is built, you can just upload it to wherever you want your documentation to be available.
Hope this helps!