Create html documentation for C# code

Question

I'm currently working on a C# project and VisualAssist generates these fancy /// <summary></summary> comments for me and I've been using them do document my code.

I assume there must be a way to use these comments to create HTML documentation like those done by Doxygen or Javadoc. How do I do that?

Answer 1

From Microsoft's documentation, their list of tools (including 3rd party) that accept XML documentation input (and generate output files) is at https://learn.microsoft.com/dotnet/csharp/language-reference/xmldoc/#tools-that-accept-xml-documentation-input and currently consists of DocFX, Sandcastle, and Doxygen. (Added this answer as I didn't see an existing link to the Microsoft list.)

Answer 2

I found something called "vsxmd" which will do this for you.

It generates markdown automatically from the XML documentation that is mentioned in Kevin Lindsay's answer above.

First, In Visual Studio (I'm using 2022), right click on your project and select properties. Go to Build->Output and check the box under "Documentation file" labeled "Generate a file containing API documentation." Take note of the output path under "XML documentation file path" as that is where your markdown will be generated.

Next, right click on your project and select Manage Nuget Packages. In the search box type "Vsxmd" from "nuget.org" as the package source.

Next build your project and the markdown documentation will be placed in the folder mentioned above.

For more information on Vsxmd, see https://github.com/lijunle/Vsxmd

If you want to convert the Markdown to HTML or something you can use stackedit.io or some other such tool. I suggest Markdown is probably the best choice for code documentation anyway due to its support by all of the various Git such as Github, Bitbucket, etc.

Answer 3

In 2017, the thing closest to Javadoc would probably DocFx which was developed by Microsoft and comes as a Commmand-Line-Tool as well as a VS2017 plugin.

It's still a little rough around the edges but it looks promising.

Another alternative would be Wyam which has a documentation recipe suitable for net aplications. Look at the cake documentation for an example.

Answer 4

The above method for Visual Studio didn't seem to apply to Visual Studio 2013, but I was able to find the described checkbox using the Project Menu and selecting my project (probably the last item on the submenu) to get to the dialog with the checkbox (on the Build tab).

Answer 5

Doxygen or Sandcastle help file builder are the primary tools that will extract XML documentation into HTML (and other forms) of external documentation.

Note that you can combine these documentation exporters with documentation generators - as you've discovered, Resharper has some rudimentary helpers, but there are also much more advanced tools to do this specific task, such as GhostDoc (for C#/VB code with XML documentation) or my addin Atomineer Pro Documentation (for C#, C++/CLI, C++, C, VB, Java, JavaScript, TypeScript, JScript, PHP, Unrealscript code containing XML, Doxygen, JavaDoc or Qt documentation).

Answer 6

This page might interest you: http://msdn.microsoft.com/en-us/magazine/dd722812.aspx

You can generate the XML documentation file using either the command-line compiler or through the Visual Studio interface. If you are compiling with the command-line compiler, use options /doc or /doc+. That will generate an XML file by the same name and in the same path as the assembly. To specify a different file name, use /doc:file.

If you are using the Visual Studio interface, there's a setting that controls whether the XML documentation file is generated. To set it, double-click My Project in Solution Explorer to open the Project Designer. Navigate to the Compile tab. Find "Generate XML documentation file" at the bottom of the window, and make sure it is checked. By default this setting is on. It generates an XML file using the same name and path as the assembly.