How do you add folder level documentation to C# assemblies?

Question

Me: I'm a relative new-comer to the .NET platform.

Problem

In Java, you can add package level documentation to your project by creating a package-info.java or package.html file and storing in the package folder. How do I add equivalent documentation to my project in C# using Visual Studio 2010?

Background

I like to write documentation describing my motivations in the package/folder level context of the source code projects that I am working on. I have become very accustomed to this workflow in a variety of languages (specifically Java) and I believe that it is a good way to document my project.

Answer 1

The focus is a bit different in .NET, it has very good support for generating IntelliSense info. Documentation at your finger tips. I'm sure you're familiar with it when you used VS for a while, look up "xml documentation".

Off-line docs used to be covered by NDoc but the guy that supported it quit his project. The Sandcastle project took up the slack. Seems to be a bit laggy too these days btw.

Answer 2

C# will automatically turn the XML-based tripple-slash comments into intellisense documentation.

///<summary>This method does something!</summary>
///<parameter name="p1">The first parameter</parameter>
///<return>true, if the method completed successfully</return>
public bool DoSomething(int p1){
  return p1 > 0;
}

When you compile your project into a class library and reference it in another project, the above will automatically be turned into a useful tooltip. In addition, the C# compiler can optionally produce an XML file with all of these comments alongside your DLL. This XML file can be fed into Sandcastle (as mentioned previously) and added to a documentation project as MSDN-style API reference.

The Sandcastle tool has its own project and documentation structure, so you'll want to start up a side project if you're going to add anything more than the XML-generated Intellisense reference.