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?

Albrecht

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
    {
    }
}

Dormeuse

So, NamespaceDoc directly? Do I put one in each directory then kind of? To have a comment for each of them... – Albrecht

Yep, will paste an example into my answer. – Dormeuse

Using public instead of internal will cause this class to appear in the help as well which is bad. – Negate

Write [System.Runtime.CompilerServices.CompilerGenerated] attribute to prevent the class showing in the documentation. – Fungible

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.

Bachelorism

Iiinteresting... Why "Documentation/*" as path? – Albrecht

Oh. It's an XPath expression to the _Namespace.xml. It is possible to store all the documentation in same XML file and just include these based on their path, ie. path='Documentation/Namespace/*' etc. The example XML uses root tag Documentation/* and is class specific so the Path just includes everything inside the root tag. – Bachelorism

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.

Tongs

Answer 4

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.

Neill

Answer 5

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

Scalenus

Answer 6

It is not possible to put comments on namespaces.

UseNamespaceDocSummaries on http://ndoc.sourceforge.net/content/documenters.htm

Shortfall

Answer 7

If using Mono's mdoc documentation system, you can document namespace members by editing the ns-*.xml documentation files.

See the mdoc file format documentation for more details.

Ravens

Answer 8

In Visual Studio it can be done by creating a Namespaces.cs file like the following:

// This file is inteded to only create the namspace comments.
// Therefore the warnig 'CS1587: XML comment is not placed on a valid language element'
// must be disabled for this file.
#pragma warning disable CS1587

// --------------------------------------------------------------

/// <summary>
/// This namespace implements the IO functionality for MyProduct
/// </summary>
namespace MyCompany.MyProduct.IO { };

// --------------------------------------------------------------
// Restore warning
#pragma warning restore CS1587

Quarto