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?

Tim Robinson · Accepted Answer · 2009-04-27T12:27:38.227

37

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

edited Apr 27 '09 at 12:27

answered Apr 27 '09 at 12:13

Tim Robinson

53,480
10
121
138

So, NamespaceDoc directly? Do I put one in each directory then kind of? To have a comment for each of them... – Svish Apr 27 '09 at 12:16
Yep, will paste an example into my answer. – Tim Robinson Apr 27 '09 at 12:26
3

Using public instead of internal will cause this class to appear in the help as well which is bad. – Admir Tuzović Apr 05 '13 at 09:28
Write [System.Runtime.CompilerServices.CompilerGenerated] attribute to prevent the class showing in the documentation. – Sergio Cabral Nov 01 '14 at 18:24

score 28 · Answer 2 · answered Apr 27 '09 at 12:27

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.

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. — Mikko Rantanen, Apr 27 '09 at 13:31

score 18 · Answer 3 · answered Sep 12 '14 at 16:19

18

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.

enter image description here

answered Sep 12 '14 at 16:19

Norbert Szenasi

993
10
24

score 3 · Answer 4 · answered Feb 29 '16 at 22:10

3

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.

answered Feb 29 '16 at 22:10

Adrian Lopez

2,601
5
31
48

MarkusE · Answer 5 · 2018-09-18T08:04:13.310

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

score 0 · Answer 6 · answered Sep 22 '09 at 02:32

0

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.

answered Sep 22 '09 at 02:32

jonp

13,512
5
45
60

score 0 · Answer 7 · answered Jul 28 '23 at 11:06

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

Kirtan · Answer 8 · 2009-04-27T12:28:02.703

0

It is not possible to put comments on namespaces.

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

edited Apr 27 '09 at 12:28

answered Apr 27 '09 at 12:10

Kirtan

21,295
6
46
61

XML-documentation for a namespace

8 Answers8

Linked