C# documentation generator?Is there any kind of documentation generator for C#? Like something that would put the xml-ish documentation right above the method/class declarations? Is there a tool or is it tucked away somewhere in VS 2008?
A comprehensive list:
Sandcastle [1]. Perhaps one of the most popular choices. Sandcastle produces accurate, MSDN style, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments. Sandcastle has the following key features: works with or without authored comments, supports Generics and .NET. (Note: Sandcastle has switched hands to SHFB. For the old Sandcastle project, go here [2].)
GhostDoc
[3]. Likely second in popularity to Sandcastle. GhostDoc is a free add-in for Visual Studio that automatically generates XML documentation comments for C#. Either by using existing documentation inherited from base classes or implemented interfaces, or by deducing comments from name and type of e.g. methods, properties or parameters. Basically it generates the /// comments above the methods, class, etc for you.
Doxygen [4]. Works across many programming languages. It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in LATEX) from a set of documented source files. (This generator is my personal choice.)
Docu [5]. A documentation generator for .Net that isn't complicated, awkward, or difficult to use. Given an assembly and the XML that's generated by Visual Studio, Docu can produce an entire website of documentation with a single command.
Nocco [6]. Nocco is a quick-and-dirty, literate-programming-style documentation generator. It is a C# port of Docco [7]. Nocco produces HTML that displays your comments alongside your code. Comments are passed through Markdown, and code is highlighted using google-code-prettify syntax highlighting.
Visual Studio will generate XML some template documentation tags for you by typing /// at the beginning of the method, variable, etc.
Natural Docs [8]. Natural Docs is an open-source documentation generator for multiple programming languages. You document your code in a natural syntax that reads like plain English. Natural Docs then scans your code and builds high-quality HTML documentation from it.
NDoc3
[9] Notable mention -- but this project appears to be sort of extinct.
Document! X [10]. Document! X is a combination of an automated .NET documentation tool and a full documentation authoring environment which can be used to create accurate, professional quality dotnet documentation for assemblies created with any .NET language (C#, Visual Basic, C++/CLI etc.). (Starting at $468 USD)
VSdocman [11]. VSdocman is an ultimate API documenting tool for every Visual Studio developer - whether you create a class library, a component, a control, an application, a smart device or a web site (ASP .NET). (Starting at $229 USD per license)
Atomineer Pro [12]. This extension for Visual Studio provides unsurpassed code documentation comment generation and updating, smart word wrapping of text within comments, live typing aids to make editing comments much easier, tools to quickly convert legacy documentation to new formats, a command to instantly align code (such as assignments, parameters and tabular data) into columns, and several handy outlining, code generation and clipboard commands. (Starting at $40 USD per license)
TwinText [13]. Another code-comment HTML document generator. Doesn't require any special markup in the comments. Has easy customization of document appearance. ($169 USD per license)
Doc-O-Matic [14]. Takes source code and comments, adds conceptual topics and external input and produces documentation from it. Generates HTML Help, PDF, Help 2, Help 3 to Web Help and Windows Help. ($49 USD)
Live Documenter [15]. The Live Documenter isn't just another .NET documentation tool, it's different. It works by displaying the documentation live for your project. Rather than an old out of date static copy. Live Documenter lets you read your comments, like a book. Always straight from the press. (50£ GBP)
I recommend you to give a look to SandCastle [1]. It generates class library documentation from .NET assemblies and the XML documentation files generated by the C# compiler. You may want to use the SandCastle GUI tools, SHFB [2] or DocProject [3] which will ease completely the document generation process.
Also give a look to the recommended and allowed XML tags [4].
Update: I agree with the Matt's comment, NDoc [5] is almost a dead project [6], and remember that you could use also the old XSLT way [7].
[1] http://sandcastle.codeplex.com//// <summary> s. Probably a way to fix that, but these are stupid defaults. - mpen
ACCEPTED]
You can start a comment with /// right above a class or class member and VS will insert some template documentation tags for you.
//***** instead of /// as marker for documentation comments (that'd be my guess from that sentence), then no. - Joey
DoSomething as Dos the something as it's commonly done may be comical, but not helpful. - Joey
I quite like GhostDoc [1]
GhostDoc is a free add-in for Visual Studio that automatically generates XML documentation comments for C#. Either by using existing documentation inherited from base classes or implemented interfaces, or by deducing comments from name and type of e.g. methods, properties or parameters.
Basically it generates the /// comments above the methods, class, etc for you. They're not perfect but provide a good starting point.
[1] http://submain.com/products/ghostdoc.aspxpublic void DataBind() - /// <summary>Datas the bind.</summary> - Chris S
BindData(). - mpen
Binds Data on public void BindData() doesn't exactly give any new information does it? - George Mauer
public string firstName { get; set; } - /// <summary>Name of the first.</summery> - modiX
As per Ray's suggestion, GhostDoc is handy, although it can lead to boilerplate docs without substance if developers are lazy.
Sandcastle [1] was originally supported by Microsoft, but is now maintained by SHFB [2]. You document using standard C# tags [3]. It has multiple output formats and plenty of flexibility. Just give whatever box you build docs on plenty of RAM.
I'd recommend SHFB to make life easy with Sandcastle. It's modeled after NDoc and works from a GUI or command line.
[1] https://sandcastle.codeplex.com/As others have said, if you want to generate the comments in your code you should have a look at GhostDoc [1].
As for outputting the comments into something nice. I recently started an open-source project for generating documentation for .Net apps, as an alternative to Sandcastle. I don't want to get into the hows or whys I've done such a thing here, but you might want to check it out. It's early days yet, but it's making steady progress.
Docu - simple documentation done simply [2]
[1] http://www.roland-weigelt.de/ghostdoc/Now (over a year later) there is NDoc3 [1]. Very easy to use.
[1] http://sourceforge.net/projects/ndoc3Doxygen [1] has been suggested in here [2]. Quoting Matt:
"Doxygen generates javadoc style documentation, although it looks like it's primarily intended to generate documentation from custom markup within your comments. Evidently, Doxygen also supports C# XML Comments... Anyway, I recommend it. It's easy to use, supports multiple languages and also generates class diagrams for you."
[1] http://www.stack.nl/~dimitri/doxygen/GhostDoc is great, but I did have a rant about adding comments some time ago. If you are going to add comments, make them usefull! [1].
[1] http://www.mellekoning.nl/index.php/2009/03/16/comments-in-code-make-them-usefull/I used a tool on a clients site when I was contracting recently called Document! X [1] (by a company called Innovasys). It includes a nifty comment editor extension in Visual Studio - i.e. a WYSIWYG editor opens up that looks like the generated documentation, including any existing xml source comments and any edits you make in there are written back as source comments. It also built the final docs for us and they looked indistinguishable from regular MSDN and worked directly from F1 in Visual Studio.
[1] http://www.innovasys.com/products/dx/dotnetdocumentation.aspxLive Documenter [1] is a free documentation tool from The Box Software.
[1] http://theboxsoftware.com/products/live-documenter/Which command will cause an XML file to be generated from documentation comments?
Ans- csc MyClass.cs /doc:MyClass.xml.
To build the XML Documentation sample within Visual Studio In Solution Explorer, right-click the project and click Properties. Open the Configuration Properties folder and click Build. Set the XML Documentation File property to XMLsample.xml. On the Build menu, click Build. The XML output file will be in the debug directory.
To build the XML Documentation sample from the Command Line To generate the sample XML documentation, type the following at the command prompt:csc XMLsample.cs /doc:XMLsample.xm
I really like Nocco (.NET port of Docco). It provides you with a side by side view of your code and the comments. Nocco documentation [1] & Source [2]
[1] http://dontangg.github.com/nocco/Works Excellent for C# (Updated 11/04/2014)
I use SandCastleHelpFile builder. It allows you to use Code Commenting, producing XML comments from your compiles. From my perspective, there's no other tool I'm interested in (personally). This is because I've already spent the time learning it, and it's free. The setup wizard is excellent.
Here's the steps:
Warning it will take you a bit of time to learn the tool and the AML (Application Markup Language). You will spend about a week learning and testing how it works. Make sure to document the namespaces and the class files too. You will want to investigate all the options and plug ins too.
With Visual Studio 2012 and 2013, Microsoft released a Nuget package for generating documentation for MVC and WebAPI projects.
Search "Microsoft.AspNet.WebApi.HelpPage" package by from Manage Nuget package or install using
For a C# application: Install-Package Microsoft.AspNet.WebApi.HelpPage
For a Visual Basic application: Install-Package Microsoft.AspNet.WebApi.HelpPage.VB
This create live documentation for all your controller definitions and classes defined in the input and output.
http://www.asp.net/web-api/overview/getting-started-with-aspnet-web-api/creating-api-help-pages
