67

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... :)

7 Answers 7

81

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.

4
  • 7
    I much prefer this over polluting the config files :| More immediately-visible in the project, too.
    – Groxx
    Mar 17, 2011 at 1:41
  • I use the Visual Studio additions so this is a real blessing. Thank you!
    – Hilydrow
    May 10, 2012 at 23:18
  • Agreed with @Groxx. I think the visibility also applies to this method over the settings of the Sandcastle project as well.
    – krillgar
    Oct 23, 2015 at 14:28
  • This methodology works well. I posted a VB.Net version of this code as a separate answer, because there is one non-obvious (to me at least) wrinkle in the C# to VB translation.
    – B Pete
    May 5, 2020 at 5:32
19

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.

3
  • 5
    The option is in Project Properties > Comments > NameSpaceSummaries Jul 29, 2010 at 12:43
  • 6
    This has actually changed in the latest version (currently 1.9.3.0) to Project Properties > Summaries > NameSpaceSummaries.
    – Ant Swift
    Jan 6, 2012 at 9:44
  • Old topic, but maybe it will be helpful to someone. It also works in version 17.1.28.0. Thanks for the tip.
    – Piotr Knut
    Mar 20, 2017 at 21:04
8

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:

.

1
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:

enter image description here

1

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

0
0

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?

0

Here is the VB.Net version of the C# code snippet shown in Tuinstoelen's accepted answer.

I am leaving this answer for those who find this question vis Google and need the VB version, since there is a gotcha waiting if you try to translate form the C# directly.

Namespace Global.TestNamespace
    ''' <summary>
    ''' The <see cref="TestNamespace"/> namespace contains classes for ....
    ''' </summary>
    <System.Runtime.CompilerServices.CompilerGeneratedAttribute()>
    Class NamespaceDoc
    End Class
End Namespace

Note the "Global." prepended to namespace to be documented. At least for my VB project configuration, this was necessary so that the name of the namespace is not nested inside the root namespace, but is the name of the root namespace. Before I prepended the "Global.", the compiler was generating a summary for "TestNamespace.TestNamespace", rather than just "TestNamespace". Given that incorrect info in the compiler generated XML file, SandCastle was not recognizing the summary as belonging to the correct namespace.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.