News for hackers. Stuff that matters.

Ask HN: C# DocGen like Javadoc?

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?

( 8 comments | 13 points | on HN )
Re:Ask HN: C# DocGen like Javadoc? by WorldMaker on Friday September 15, 2017 @05:31PM (#15260941)
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/

Re:Ask HN: C# DocGen like Javadoc? by binarynate on Friday September 15, 2017 @07:05PM (#15261579)
+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.
Re:Ask HN: C# DocGen like Javadoc? by eschutte2 on Friday September 15, 2017 @03:06PM (#15259841)
Re:Ask HN: C# DocGen like Javadoc? by noaccounthere on Friday September 15, 2017 @03:44PM (#15260166)
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.

Re:Ask HN: C# DocGen like Javadoc? by alistproducer2 on Sunday September 17, 2017 @03:57PM (#15271392)
This was the solution I went with. As you mentioned, It is incredibly slow.
Re:Ask HN: C# DocGen like Javadoc? by tjr on Friday September 15, 2017 @03:02PM (#15259796)
Re:Ask HN: C# DocGen like Javadoc? by talles on Friday September 15, 2017 @05:39PM (#15260997)
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.

Re:Ask HN: C# DocGen like Javadoc? by scopecreep on Friday September 15, 2017 @03:33PM (#15260069)
That looks a lot like the format for auto-generated method comments from VS.net ~2013 or so.