Namespace documentation on a .Net project (Sandcastle)?

Question

Hello,

I started using Sandcastle some time ago to generate a Documentation Website for one of our projects. It's working quite well but we've always only written documentation for classes, methods, properties (...) in our project and had completely separate documentation for the overall project and project parts/modules/namespaces. It would be nice if I could merge that documentation together and add respective documentation to the generated helper files but I can't figure out how to do it.

Just adding comments to the namespace declaration doesn't seem to work (C#):

/// <summary>
/// My short namespace description
/// </summary>
namespace MyNamespace { ... }

Does anyone know how to do this? I know it's possible somehow and it would be really nice to have... :)

Answer 1

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.

Answer 2

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)

.

Answer 3

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.