命名空间的XML文档

Question

你会为命名空间编写xml-doc吗？如果是的话,如何以及在哪里？

我想,如果有可能,可能是一个几乎空的文件,如下所示:

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

}

但那会有用吗？既然你......"声明",或者至少在所有其他文件中都使用了命名空间......如果你在同一个命名空间的其他地方写了一个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还略微扩展了语法,并允许直接从代码文件中嵌入代码示例.一个例子_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帮助文件生成器支持对命名空间的注释.打开您的Sandcastle项目.在Project Properties窗口中导航到Summaries并单击Edit Namespace Summaries按钮.