HN Explorer

Ask HN: C# DocGen like Javadoc?

13 points by alistproducer2 ↗ HN
There's an internal team at my job that's trying to get people to use a framework they built. The problem is there's no documentation; this despite the code being well commented in what appears to be a structured fashion. An example looks like this:

/// <summary>

/// Waits for the Page's DOM to fully.....

/// </summary>

/// <param name="classInstance">The PageObject instance to be populated.</param>

does anyone recognize this format and, even better, a tool used to turn this into usable HTML documentation?

9 comments

[ 3.1 ms ] story [ 30.9 ms ] thread
[deleted]
(comment deleted)
scopecreep
That looks a lot like the format for auto-generated method comments from VS.net ~2013 or so.
noaccounthere
https://dotnet.github.io/docfx/

I believe this is used to generate some of the official Microsoft documentation.

We use it on our team -- it's pretty basic, but allows Markdown formatted content and ingests the triple slash comments.

The biggest downside is that it is extremely slow.

alistproducer2
This was the solution I went with. As you mentioned, It is incredibly slow.
WorldMaker
Those comments auto-build an XML output; it's a built-in feature of the C# compiler. [1]

There are a number of XSLT stylesheets and more complicated tools around, many from relatively ancient times in the .NET world, to generate prettier documentation from those comments. NDoc [2] is ancient but still presumably works. I last used SandCastle, whose website proclaims it shutdown and forwards to fork SHFB [3], and some of whose guts inspired DocFX [4].

As another comment points out it appears that DocFX is the latest toolset Microsoft themselves are using (it's one of a couple of build tools for the new mostly all open source docs.microsoft.com site).

[1] https://docs.microsoft.com/en-us/dotnet/csharp/programming-g...

[2] http://ndoc.sourceforge.net/

[3] http://github.com/EWSoftware/SHFB

[4] https://dotnet.github.io/docfx/

binarynate
+1 for Sandcastle (SHFB). I used it a couple of years ago and felt that it was pretty easy to use and that the documentation came out nicely.
talles
In Visual Studio, if you're distributing it via NuGet package you can send the xml doc along with the code and consume it via Intellisense (as you type it), similar to what happens when you use the .NET framework itself.

Right click the project, "Properties", "Build", enable "XML documentation file". When creating the NuGet package make sure the xml is in the same folder as the dll.