命名空间的XML文档

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

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

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

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

Answer 1

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

编辑：例如：

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

Answer 2

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文件中为帮助文件写更大的描述。 这样的代码是不是所有的细节混乱，仍然易于阅读。

Answer 3

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

Answer 4

你可以在doxygen中使用：

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

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

Answer 5

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

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

Answer 6

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

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