命名空间的XML文档

你会写一个命名空间的XML文档? 如果是,如何和在哪里?

我会想,如果可能的话,可能是这样一个几乎空的文件:

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

但是,这会工作吗? 既然你…“声明”,或者至less在所有其他文件中使用命名空间…以及如果你在同一个命名空间的其他地方写了一个xml文档的东西会发生什么? 会不会有人离开? 或者他们会以某种方式合并?

NDoc通过识别位于每个命名空间的特殊NamespaceDoc类以及使用它的文档来支持这一点。 我还没有尝试过,但Sandcastle似乎支持相同的技巧。

编辑:例如:

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

Sandcastle不直接支持NamespaceDoc,但是如果使用Sandcastle帮助文件生成器 ,则可以使用Tim提到的NamespaceDoc类。

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

SCHB还稍微扩展了语法,允许直接从代码文件中embedded代码示例。 一个例子_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> 

在XML文件中包含文档允许您在代码中写简短的摘要,在单独的XML文件中为帮助文件写更大的描述。 这样的代码是不是所有的细节混乱,仍然易于阅读。

Sandcastle Help File Builder支持对命名空间的评论。 打开你的Sandcastle项目。 在“ Project Properties窗口中,导航到“ Summaries ,然后单击“ Edit Namespace Summariesbutton。

在这里输入图像说明

你可以在doxygen中使用:

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

此外,在NameSpaces.cs文件中声明名称空间是一种很好的做法,并且仅在此文件中注释它们。

不可能对命名空间进行注释。

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

如果使用Mono的mdoc文档系统,则可以通过编辑ns – *。xml文档文件来logging名称空间成员。

有关更多详细信息,请参阅mdoc文件格式文档 。