XML-documentation for a namespace

Question

Would you write xml-doc for a namespace? And if yes, how and where?

I would think, if it is possible, maybe an almost empty file like this:

/// <summary>
/// This namespace contains stuff
/// </summary>
namespace Some.Namespace
{

}

But will that work? Since you... "declare", or at least use the namespace in all the other files as well... and what would happen if you wrote an xml-documentation thing somewhere else on the same namespace? Would one be gone? Or would they be merged somehow?

Answer 1

NDoc supports this by recognising a special NamespaceDoc class located in each namespace, and using the documentation from that. I haven't tried it, but Sandcastle appears to support the same trick.

Edit: For example:

namespace Some.Namespace
{
    /// <summary>
    /// This namespace contains stuff
    /// </summary>
    public static class NamespaceDoc
    {
    }
}

Answer 2

Sandcastle does not support the NamespaceDoc directly, but if you use Sandcastle Help File Builder you can use the NamespaceDoc class mentioned by Tim.

namespace Example
{
    /// <summary>
    ///   <para>
    ///     Summary
    ///   </para>
    /// </summary>
    /// <include file='_Namespace.xml' path='Documentation/*' />
    internal class NamespaceDoc
    {
    }
}

SCHB also extends the syntax slightly and allows embedding code examples straight from code files. An example _Namespace.xml:

<?xml version="1.0" encoding="utf-8" ?>
<Documentation>
  <summary>
    <h1 class="heading">Example Namespace</h1>
    <para>
      This namespace is used in the following way:
    </para>

    <code source="Examples\Class.cs" lang="cs"></code>
    <code source="Examples\Class.vb" lang="vbnet"></code>

    <para>
      Hopefully this helps!
    </para>
  </summary>
</Documentation>

Including documentation in XML file allows you to write short summary in code and larger description in a separate XML file for the help file. This way the code isn't cluttered with all the details and remains easily readable.

Answer 3

Sandcastle Help File Builder supports comments on namespaces. Open your Sandcastle project. In Project Properties window navigate to Summaries and click on the Edit Namespace Summaries button.

Answer 4

If you use Sandcastle and its "Help File Builder" you can document namespaces and Namespace-Groups using the following Code in your Projects:

namespace Company.Product.Widgets
{
    /// <summary>
    /// These are the namespace comments for <c>Company.Product.Widgets</c>.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceDoc
    {
    }
}

If the project has namespace grouping enabled, you can also maintain the namespace group comments using a NamespaceGroupDoc class in a similar fashion. The following is an example:

namespace Company.Product
{
    /// <summary>
    /// These are the group comments for namespaces in <c>Company.Product</c>.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceGroupDoc
    {
    }
}

To keep the NamespaceDoc class from appearing in the help file, leave off the public keyword and mark it with a CompilerGenerated attribute.

For Reference see here: https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

Answer 5

You can do it in doxygen using:

/// <summary>
/// description
/// </summary>
namespace name{};

Also, it's a good practice to declare your namespaces in a NameSpaces.cs file, and comment them only in this file.