Is it me, or have many people/projects stopped creating good API documentation via Inline XML comments in their source code.  A couple of years ago when nDoc was in full swing it seemed to be taboo if you did not markup your source code with good XML Comments and generate accompanied API documents.

For those of you who many be asking what is he talking about, Inline XML comments in your source?  Well, that would be (in C#) all those /// comments you see from time to time in source code like so.

namespace TestNamespace
{
/// <summary> 
///    Tests whether sandcastle can handle all c# tags as defined at 
///    http://msdn2.microsoft.com/en-us/library/5ast78ax.aspx. 
///    Comments of method "Increment (int step)" include almost all tags. 
///    Method "Swap" is used to test generics tags, such as "typeparam". 
///    <threadsafety static="true" instance="false"/> 
/// </summary> 
[Serializable()]
public class StoredNumber
{  

/// <summary> 
///    Initializes the stored number class with a starting value. 
/// </summary> 
public StoredNumber( int value )
{ number = value; }

However today, I have noticed that many open source projects and a good share of commercial applications do not bother marking up their source code with XML comments. Maybe one contributing factor is that nDoc died, ok you can still download version 1.3 but it is over two years old now and Microsoft’s answer to this solution Sandcastle is not quite as snazzy as nDoc was i.e. Command-line interface, or maybe propel are just not aware of their options. 

The following information outlines what you need to install so you can create proper Inline API (MSDN-style) documentation.  Here is a list of programs you need to install.

Sandcastle:

Microsoft home page for Sandcastle

You can download it from CodePlex http://www.codeplex.com/Sandcastle

Sandcastle, created by Microsoft, is a free tool used for creating MSDN-style documentation from .NET assemblies and their associated XML comment files. It is command-line based and has no GUI front-end, project management features, or an automated build process

SHFB (Sandcastle Help File Builder):

You can download SHFB from CodePlex http://www.codeplex.com/SHFB

SHFB is a GUI interface that almost looks identical to the NDoc interface so anyone familiar with NDoc should be quite comfortable using it.  It uses the underlining Sandcastle API to generate an HTML 1.x (.CHM) file, an HTML 2.x (.HxS) file, and/or a web site.

SHFB Requirements

In order to use SHFB you will need the following:

- The .NET 2.0 Framework

- The latest version of Sandcastle. 
- The HTML Help Workshop for building HTML Help 1.x (.CHM) help files

- The HTML 2.x compiler for building HTML Help 2.x (.HxS) help files

You can obtain the HTML builders by installing the Visual Studio 2008 SDK these are the latest builds.

XML Documentation Comments Guide:

Home page http://www.dynicity.com/downloads/default.aspx

Download the “Windows Installer” at http://www.dynicity.com/downloads/XMLDocCommentsGuide.exe

This is a help file with a very nice collection of information on how to use XML Comment tags properly in your source code, it has lots of links to some good tutorials and examples. 

DocProject for 2008:

Home page from CodePlex for DocProject

DocProject drives the Sandcastle help generation tools using the power of Visual Studio 2005/2008 and MSBuild. Choose from various project templates that build compiled help version 1.x or 2.x for all project references. DocProject facilitates the administration and development of project documentation with Sandcastle, allowing you to use the integrated tools of Visual Studio to customize Sandcastle’s output.

Example Links:

.NET Documentation Guidelines (version 2.5)

http://p3net.mvps.org/downloads/docs/DocGuidelines.doc 

XML Documentation in C# (Anson Horton, C# Compiler Program Manager)

http://cyrino.members.winisp.net/9112006/XMLDocs.doc

C# XML Documentation (Alan Dean)

http://thoughtpad.net/alan-dean/cs-xml-documentation.html

C# and XML Source Code Documentation

Documenting C# source code with XML Comments

Scott Nichols Esoterica Architecture and Design, Esoterica, Microsoft, Open Source Software, Tools and Utilities, XML