Namespace documentation on a .Net project (Sandcastle)?

Use Sandcastle Help File Builder. It allows to specify namespace descriptions in the XML project file

Example:

<namespaceSummaryItem name="System" isDocumented="True">
    Generic interfaces and helper classes.
</namespaceSummaryItem>

References:

• example of Open Source project that generates documentation with every build (all scripts are in the trunk).
• That's how the documentation by SHFB looks like on the Web (it is deployed on every forced build)

.

If you use Sandcastle Help File Builder there is a dialog to enter the Namespace summaries. (Apparently also support for defining a specific class, but I wouldn't prefer it..)

From the feature list:

Definition of project summary and namespace summary comments that will appear in the help file. You can also easily indicate which namespaces to include or exclude from the help file. Support is also included for specifying namespace comments via a NamespaceDoc class within each namespace.

Sandcastle also supports the ndoc-style namespace documentation, which allows you to stick the documentation in the source files:

Simply create a non-public class called NamespaceDoc in the namespace you want to document, and the xml doc comment for that class will be used for the namespace.

Adorn it with a [CompilerGenerated] attribute to prevent the class itself from showing up in the documentation.

Example:

namespace Some.Test
{
    /// <summary>
    /// The <see cref="Some.Test"/> namespace contains classes for ....
    /// </summary>

    [System.Runtime.CompilerServices.CompilerGenerated]
    class NamespaceDoc
    {
    }
}

The work item in SandCastle is located here.