4 ms·

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?

tjr 9y ago
Looks like maybe: http://www.stack.nl/~dimitri/doxygen/manual/xmlcmds.html http://www.stack.nl/~dimitri/doxygen/manual/xmlcmds.html
eschutte2 9y ago
This is a Visual Studio feature. https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments https://docs.microsoft.com/en-us/dotnet/csharp/programming-g...
deleted 9y ago
[deleted]
scopecreep 9y ago
That looks a lot like the format for auto-generated method comments from VS.net ~2013 or so.
noaccounthere 9y ago
https://dotnet.github.io/docfx/ 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 9y ago
  This was the solution I went with. As you mentioned, It is incredibly slow.
WorldMaker 9y ago
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-guide/xmldoc/xml-documentation-comments https://docs.microsoft.com/en-us/dotnet/csharp/programming-g... [2] http://ndoc.sourceforge.net/ http://ndoc.sourceforge.net/ [3] http://github.com/EWSoftware/SHFB http://github.com/EWSoftware/SHFB [4] https://dotnet.github.io/docfx/ https://dotnet.github.io/docfx/
- binarynate 9y ago
  +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 9y ago
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.

tjr 9y ago

Looks like maybe: http://www.stack.nl/~dimitri/doxygen/manual/xmlcmds.html http://www.stack.nl/~dimitri/doxygen/manual/xmlcmds.html

eschutte2 9y ago

This is a Visual Studio feature. https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments https://docs.microsoft.com/en-us/dotnet/csharp/programming-g...

deleted 9y ago

[deleted]

scopecreep 9y ago

That looks a lot like the format for auto-generated method comments from VS.net ~2013 or so.

noaccounthere 9y ago

https://dotnet.github.io/docfx/ 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 9y ago
This was the solution I went with. As you mentioned, It is incredibly slow.

WorldMaker 9y ago

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-guide/xmldoc/xml-documentation-comments https://docs.microsoft.com/en-us/dotnet/csharp/programming-g... [2] http://ndoc.sourceforge.net/ http://ndoc.sourceforge.net/ [3] http://github.com/EWSoftware/SHFB http://github.com/EWSoftware/SHFB [4] https://dotnet.github.io/docfx/ https://dotnet.github.io/docfx/

binarynate 9y ago
+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 9y ago

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.