XML documentation for namespace

Question

Could you write xml-doc for namespace? And if so, how and where?

I would think, if possible, perhaps an almost empty file like this:

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

But will it work? Since you ... declare, or at least use the namespace in all other files ... and what happens if you write xml documentation elsewhere in the same namespace? Will anybody disappear? Or did they somehow merge?

Answer 1

NDoc supports this by recognizing the special NamespaceDoc class located in each namespace and using the documentation from it. I haven't tried it, but Sandcastle seems 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 NamespaceDoc directly, but if you use the Sandbule 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 a bit and allows you to embed code samples directly from code files. 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 an XML file allows you to write a short summary in code and a more detailed description in a separate XML file for the help file. Thus, the code is not cluttered with all the details and remains easy to read.

Answer 3

Sandcastle Help File Builder supports namespace comments. Open the Sandcastle project. In the Project Properties window Project Properties go to Summaries and click the Edit Namespace Summaries button.

Answer 4

You can do this in doxygen using:

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

In addition, it is recommended that you declare your namespaces in the NameSpaces.cs file and comment on them only in this file.

Answer 5

Cannot put comments in namespaces.

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

Answer 6

If you use Mono mdoc , you can document namespace elements by editing the ns - * .xml documentation files.

See the mdoc file format documentation for more details.