Introduction

In .NET projects, Sandcastle and Sandcastle Help File Builder can generate namespace pages, but namespaces do not have a direct source-level declaration that accepts XML comments the way classes and methods do. The usual solution is the NamespaceDoc pattern: create a placeholder type inside the namespace and attach the summary comment to that type so the documentation tool has something concrete to read.

Why Namespace Documentation Needs a Placeholder

C# lets you put XML comments on types and members easily:

1/// <summary>
2/// Calculates invoice totals.
3/// </summary>
4public class InvoiceCalculator
5{
6}

A namespace block does not work the same way for documentation generation. Even though a namespace is a real organizational concept, tools such as Sandcastle typically need a documented symbol in the assembly and XML comment file to populate the namespace page.

That is why namespace documentation usually lives on a helper type rather than on the namespace block itself.

The NamespaceDoc Pattern

The common convention is to create an internal class named NamespaceDoc inside the namespace and document that class.

1namespace MyCompany.Project.Billing
2{
3    /// <summary>
4    /// Contains billing services, invoice models, and tax calculation helpers.
5    /// </summary>
6    [System.Runtime.CompilerServices.CompilerGenerated]
7    internal class NamespaceDoc
8    {
9    }
10}

Sandcastle Help File Builder recognizes this pattern and uses the XML summary as the namespace description in the generated help output.

The class is not meant to be instantiated or referenced at runtime. It exists only to anchor documentation.

Make Sure XML Comments Are Generated

The placeholder does nothing if the project does not emit an XML documentation file during build. In an SDK-style project, enable that in the project file:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Without the XML output, Sandcastle has far less information to work with. The source comments may exist, but the documentation pipeline never receives them in the form it expects.

Document the Namespace, Not the Placeholder

The summary text should describe the namespace as an architectural group, not the NamespaceDoc helper itself.

Good namespace documentation usually answers:

• what kinds of types live here,
• what responsibility this namespace has,
• how it differs from nearby namespaces,
• what layer or subsystem boundary it represents.

For example:

1namespace MyCompany.Project.Security
2{
3    /// <summary>
4    /// Provides authentication, authorization, token validation, and identity-related services.
5    /// </summary>
6    internal class NamespaceDoc
7    {
8    }
9}

That is much more useful than a generic sentence such as "Contains security classes."

One Namespace, One Placeholder

If your library has several major namespaces, give each one its own NamespaceDoc.

1namespace MyCompany.Project.Reporting
2{
3    /// <summary>
4    /// Contains report models, export writers, and dashboard integration components.
5    /// </summary>
6    internal class NamespaceDoc
7    {
8    }
9}
10
11namespace MyCompany.Project.Notifications
12{
13    /// <summary>
14    /// Contains email, SMS, and in-app notification delivery services.
15    /// </summary>
16    internal class NamespaceDoc
17    {
18    }
19}

This produces clearer generated help because readers can understand the library at the namespace level before diving into individual classes.

Common Pitfalls

• Putting XML comments on the namespace block and expecting Sandcastle to use them directly.
• Forgetting to enable XML documentation generation in the project.
• Making the placeholder public, which can unnecessarily clutter the public API surface.
• Writing generic filler text that explains nothing about the namespace's real responsibility.
• Using one placeholder style in some namespaces and none in others, which leads to uneven generated documentation.

Summary

• Sandcastle typically uses the NamespaceDoc convention to populate namespace pages.
• Add an internal NamespaceDoc type inside each namespace you want to describe.
• Put the XML summary on that placeholder type, not on the namespace block.
• Ensure the project emits an XML documentation file during build.
• Write namespace summaries that explain purpose and boundaries, not just names.