Namespace documentation on a .Net project (Sandcas

Question

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

I see documentation for an "External XML Comments Files". Showing a schema like:

<doc>
    <assembly/>
    <members>
        <member/>
    </members>
</doc>

If this is placed in a separate file, what would the extension be (xml/aml) and can this be used in the Visual Studio project?

Answer 2

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.

Answer 3

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 4

I know it's an old post, but this may be of help to someone else.

Following this link, you can set a description for the namespaces without the need of adding a non-public class to your project.

To edit the namespace summaries, expand the Summaries section within the Project Properties tab in SHFB. You will see a setting named, "NamespaceSummaries", which initially shows the value, "(None)". Click the setting to select it and a button showing an ellipsis symbol (...) appears. Click this button to display the Namespace Summaries dialog box, pictured below:

Answer 5

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 6

You cant add references that way - do it via NamespaceDoc.cs instances

i.e

/// <summary> /// Concrete implementation of see cref="IInterface" using see cref="Concrete"
/// </summary> class NamespaceDoc { }

see here