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?

But Doxygen uses different syntax. Since Visual Assist already generates these comments for me I'd rather use them. Edit: actually maybe it supports xml as well, I'll give it a go. — jaho, Mar 09 '13 at 22:07
Nothing wrong with Doxygen per se I guess, but if you started documentation with the Microsoft XML style, then maybe you locked in to use it. (As we do not want to translate to Doxygen). — stephanmg, Feb 21 '20 at 20:10

score 58 · Accepted Answer · edited Mar 20 '17 at 19:16

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

score 54 · Answer 2 · answered Jun 10 '17 at 07:57

54

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.

answered Jun 10 '17 at 07:57

mode777

3,037
2
23
34

1

Docfx worked perfectly for me. I does work for VS2015 as well - just add nuget package `docfx.console`. – Anton Krouglov Jul 21 '17 at 08:21
1

The most voted answer is from 2009, but today (2017) I would say docfx is the best way to go. – Nikolaos Georgiou Aug 03 '17 at 05:57
2

DocFX has unfortunately the big disadvantage, that it focuses only on documentation ofr the public. So if you want to do some documentation for internal use, which also includes access modifiers "internal" or "private", it is absolute useless. Sure... you have the opportunity to modify the code by yourself and fix this. See: https://github.com/dotnet/docfx/issues/836 – Onsokumaru Dec 21 '17 at 13:28
Wyam has been superseeded by [Statiq](https://www.statiq.dev/framework). – MovGP0 Jun 09 '22 at 15:25
4

Note: docFX is dead as a project (outstanding bugfixes/patches are now 2+ years and waiting, and it relies on upstream libs like wkhtmltopdf that stopped being maintained 2+ years ago and no longer run). The official page has said for 1+ years 'we have a replacement we're using internally, but we're not letting anyone else have it yet'. Don't waste time on it! – Adam Aug 26 '22 at 19:32
@Adam do they mention this anywhere? I have seen docFX is actively maintained. – Albert Einstein Apr 08 '23 at 09:45
@KiranShahi DocFx version 2 is still maintained and Microsoft is still using it heavily as part of their documentation stack. Is it still in active development in terms of new features? I wouldn't expect much tbh. Version 3 seems abandoned and it would be nice to get an official statement on this. When doing docs on C# code i still think it's the best option out there. – mode777 Apr 11 '23 at 12:22
1

@mode777 Version 3 is not abandoned, they just made it private for their internal use particularly for learn.microsoft.com. As per the comment made by Mark Smith it will continue to evolve! https://github.com/dotnet/docfx/discussions/8277#discussioncomment-4409645 – Albert Einstein Apr 11 '23 at 13:30
@KiranShahi thanks for pointing out that post to me. However I read into it that they will cherry-pick **some** features from the V3 branch but there won't be a V3 release because it broke to much. However, we can see that the project is alive even though development seems to be closely aligned with what Microsoft needs for their docs. – mode777 Apr 11 '23 at 13:57

score 3 · Answer 3 · edited Jun 20 '20 at 09:12

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.

He's not asking how to generate the XML documentation, he's asking how to turn that XML documentation into HTML. — Mark, May 13 '15 at 20:59
While your answer doesn't answer the OP's question, it answers mine. Thanks! — Tony Vitabile, Jun 04 '15 at 16:29

score 3 · Answer 4 · answered May 03 '17 at 21:03

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

score 0 · Answer 5 · answered Jun 16 '23 at 03:49

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.

score 0 · Answer 6 · answered Aug 06 '23 at 09:32

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

Create html documentation for C# code

6 Answers6

Linked