How to produce CSharp API Documentation

Introduction

In C#, documentation for code can be created by including XML tags in special comment fields in the source code directly before the code block they refer to.

This article explains what steps and tools are necessary to produce an API Documentation out of these code comments that is similar to the .NET Framework documentation which is found on MSDN.

Quick overview of the steps to produce API-style documentation

1. Add XML comments to your .cs code files
2. Compile the C# Project that the .cs file is part of so that the XML Comments get extracted and end up in a separate XML file.
3. Use Sandcastle Help File Builder with an already existing SHFB Project (or create a new Project) that references the compiled DLL/EXE. SHFB will execute Sandcastle, which will pull in the XML Comment Tags from the XML file that has the same name as the DLL/EXE (exept that it has an .xml extension).
4. Once SHFB has finished the build process OK (which can be quite time consuming!), you should end up with a HTMLHelp file with an .chm extension. It will contain the full Namespace and Class structure of the DLL(s) referenced in the SHFB Project and all the XML Comment Tags that you have placed in the .cs file(s) of the C# Project(s)!

Process Steps

Step 1: Adding XML Comments

XML Comments in Source Code

For the format and the usage of XML Comments and XML Comment Tags in source code please refer to XML Documentation Comments: How-To

Note: The XML Comment Tags get extracted by the C# compiler only when the compiler is specifically told to do so (see Switching XML Comment Tag extraction on). It does not happen by default!

Option: include/reference external XML Comments in Source Code comments

Microsoft specified a special XML tag, <include>, for the inclusion of (potentially) very long XML comments that one would not want to be part of the source code. This tag allows referencing a specific XML element in an arbitrarily formatted valid XML document. The content of that XML element is 'pulled in' and inserted at the exact point where the <include> tag is placed in XML Comments in source code.

Example: <codepre> /// <summary> /// Partner Edit screen. /// </summary> /// <include file='doc.extra/Ict.Petra.Client.MPartner.Gui.xml' /// path='doc/members/member[@name="T:Ict.Petra.Client.MPartner.TPartnerEditDSWinForm"]/*' /> </codepre>

This <include> tag tells the compiler to

• replace the whole content of the <include> tag
• at the exact position where this tag is located
• with the content that is found in the XML Element named 'T:Ict.Petra.Client.MPartner.TPartnerEditDSWinForm'
  • where the XML Element can be located in XPATH 'doc/members/member'
    • in the xml file 'Ict.Petra.Client.MPartner.Gui.xml'
      • which lies in sub-directory 'doc.extra' (this sub-directory is searched for under the directory where the project file lies that references the .cs file in which the <include> tag is found).

Notes:

1. As mentioned in the previous paragraph, the XML file can be an arbitrarily formatted valid XML document. This example shows how to reference an XML Element in a file that has exactly the same structure as the XML file that is generated by the C# compiler and the 'DocMounter' tool.
2. The content of the XML Element that is referenced can include the same XML Tags as the XML Comment in the source code! In that case the two tags get concatenated into one tag. E.g in the example above, the content of the external XML Element could contain a <summary> Tag. Since this tag is also contained in the XML Comment in the source code, the content of the two <summary> tags becomes one <summary> tag, where the content of the external XML Element is appended to the content in the XML Tag found in source code.

Step 2: Compilation / Extraction of XML Comment Tags from Source Code

The Microsoft C# Compiler extracts the XML Documentation Tags from the .cs Source Code file into an XML file that has a specific structure. That file is named like the project file of which the .cs file is part of (execpt that it has an XML extension). It gets placed in the same directory where the DLL/EXE goes that results from the compiled project (in our case that will be the respective _bin/Debug directory).

Example: If the Ict.Petra.Client.MPartner.Gui project is built with the compiler documentation switch set to on, the C# compiler will parse any .cs file that is part of that project and put all found XML Tags into an XML file called Ict.Petra.Client.MPartner.Gui.xml which will be placed in the U:\openpetraorg\csharp\ICT\Petra\Client\_bin\Debug directory.

Switching XML Comment Tag extraction on

The extraction of the XML Comment Tags does not happen by default if a C# project is compiled! The C# Compiler needs to specifically told to extract the XML tags. This can be done by either specifying a Project Option in the IDE (in SharpDevelop: right-click the Project in the Projects Tree, select Properties, select 'Compiling' Tab, tick 'XML documentation' in the 'Output' GroupBox) or by using the /doc command line switch of the command line C# Compiler (csc.exe).

Note: the extraction of the XML Comment Tags is very fast. Even on a larger project (e.g. Ict.Petra.Client.MPartner.Gui) it takes only a few seconds longer to compile the Project with XML Comment Tags switched on compared to when it is switched off.

XML Comment Tags Warnings reported by the C# compiler

While the C# Compiler is extracting the XML tags from the .cs files it does some checks on them to highlight common problems and typos to the developer.

Here is a list of tags that the compiler performs checks on:

• <param> tag: checks for the presence of all <param> tags for methods.
• <typeparam> tag: like <param> tag, but checks for the Type Parameter of a Generic Method.
• <see> tag and <seealso> tag: checks that the given code element exists.
• <exception> tag: checks that the given exception exists.
• <permission> tag: checks that the given code element exists.
• <include> tag: checks for the presence of the referenced XML element in the specified external XML file.

The C# compiler emits these warnings like any other source code warnings, i.e. in the IDE in the 'Errors' pane, where the developer can click on them and jump to the offending source code line.

Including of XML Comments from external XML files

The merging of XML Comments from external XML files with XML Comment Tags in the source code files happens at the C# compilation stage (see Option: include/reference external XML Comments in Source Code comments for details on how to do that).

Step 3: Creation of HTMLHelp (.chm) file

Sandcastle Help File Builder (SHFB)

SHFB is a GUI application that allows to create Projects for the building of API-style documentation with Sandcastle. It is apparently similar to the GUI for NDoc (the now discontinued open source documentation tool for .NET 1.1).

A SHFB 'Project' references 1..n DLLs (and their XML Documentation files) and contains settings that direct how Sandcastle will build the resulting documentation. SHFB 'remote-controls' Sandcastle via custom-generated .bat and .config files and shows the build progress along with all its outputs.

Once finished with the building of the HTMLHelp file (which can be quite time consuming!), a HTMLHelp file with extension .chm will be available. It will contain the full Namespace and Class structure of the DLL(s) referenced in the SHFB Project and all the XML Comment Tags that have been placed in the .cs file(s) of the C# Project(s)!

SHFB has an extensive built-in Help documentation with lots of links to resources on XML Comment Tags, Sandcastle and more.

Microsoft Sandcastle

Sandcastle is the name of the tool that Microsoft themselves developed for the purpose of generating the .NET Framework API Documentation (for .NET 1.0, 1.1, 2.0, 3.0 and 3.5). It has been released into the public in January 2008.

HTMLHelp Documentation that is generated by Sandcastle can look strikingly similar to the .NET Framework API Documentation, but other presentation styles are possible as well.

Sandcastle isn't a single application but consists of several commandline applications that together form the Sandcastle product. The generation of API-style HTMLHelp documentation of the quality and sophistication of the .NET Framework API Documentation is a quite complicated, multi-step process. Microsoft broke down the process into several steps and each step has a commandline application for performing it, and each commanline application has its own .config file that configures its operation.

All in all, the direct usage of Sandcastle is complicated, somewhat abstract and cumbersome. That's why several GUI Applications have been developed, of which the 'Sandcastle Help File Builder' seems to be the best.

Overview: Tools Needed

Microsoft C# Compiler

This is the normal Microsoft C# compiler (csc.exe, .NET 1.0 and higher). It is installed by default with the .NET SDK.

It is the C# Compiler that extracts the XML Documentation Tags from the .cs Source Code file into a XML file. This XML file is the only source of the XML Documentation Tags (except for XML files that are referenced with the <include> tag (Option: include/reference external XML Comments in Source Code comments.

Microsoft Sandcastle

Sandcastle is the set of applications that build HTMLHelp (.chm) files from extracted XML Comment Tags.

Sandcastle is hosted on CodePlex: http://www.codeplex.com/Sandcastle.

Note: Sandcastle needs to be installed in order for Sandcastle Help File Builder to work!

Sandcastle Help File Builder (SHFB)

SHFB is a GUI application that allows to create Projects for the building of API-style documentation with Sandcastle.

SHFB is published on CodePlex - Sandcastle Help File Builder and can be downloaded from there.

Note: SHFB always works only with a specific version of Sandcastle - therefore make sure that the correct Sandcastle version is installed on your PC when using a given SHFB version (Christian used SHFB Version '1.8.0.0 Alpha' with Sandcastle Version '2.4.10520' [May 2008 Release])!

Microsoft Help Workshop

Microsoft Help Workshop, also known as HTML Help 1.4 SDK, is needed by Sandcastle for the creation of HTMLHelp 1.x files (.chm extension). Therefore it needs to be installed before HTMLHelp files can be generated from XML Comment Tags.

HTML Help 1.4 SDK Download

DocMounter

DocMounter allows creation of XML Files that contain external XML Comment Tags.

This is an optional tool. It is quite useful for entering longer or heavily formatted XML Comments because it supports the creation of HTML tags (eg. lists with bullets) with menu commands.

DocMounter Product Page

Attention: DocMounter can't read at the moment the .dll files of OpenPetra.

Example Projects and resulting example API Documentation

Christian has committed several files in the

U:\openpetraorg\csharp\ICT\Petra\Client\lib\MPartner\gui\doc.extra

folder. Get that folder from git for the examples.

Folder contents:

• MPartner_Gui.shfb: SHFB project file.
  • Open this in Sandcastle Help File Builder to get started. You should be able to build the API documentation right away if you have installed Sandcastle, SHFB and HTML Help Workshop correctly on your PC.
• MPartner_Gui_API.chm: example of the API Documentation that results from MPartner_Gui.shfb.
• Ict.Petra.Client.MPartner.Gui.xml: Example of an external XML file for the specification of external XML Comment Tags.
  • that file is 'imported' in the PartnerEdit.cs/TPartnerEditDSWinForm XML Class Comment Tag and so its contents become part of the API-style documentation for that Class. This XML file has been built using the 'DocMounter' application.
• MPartner_Gui.dmproj: DocMounter project for creating the 'Ict.Petra.Client.MPartner.Gui.xml' file.

Attention: The current DocMounter application can't read the .dll files of OpenPetra.