命名空间的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 Help File Builder，你可以使用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按钮。

Answer 4

你可以在doxygen中使用：

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

此外，最好在NameSpaces.cs文件中声明命名空间，并仅在此文件中对其进行注释。

Answer 5

如果您使用Sandcastle及其“帮助文件生成器”，您可以使用项目中的以下代码记录名称空间和命名空间组：

namespace Company.Product.Widgets
{
    /// <summary>
    /// These are the namespace comments for <c>Company.Product.Widgets</c>.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceDoc
    {
    }
}

如果项目启用了命名空间分组，您还可以使用NamespaceGroupDoc类以类似的方式维护命名空间组注释。以下是一个例子：

namespace Company.Product
{
    /// <summary>
    /// These are the group comments for namespaces in <c>Company.Product</c>.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceGroupDoc
    {
    }
}

要使NamespaceDoc类不显示在帮助文件中，请不要使用public关键字并使用CompilerGenerated属性对其进行标记。

有关参考，请参阅此处：https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

Answer 6

无法对命名空间进行注释。

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

Answer 7

如果使用Mono的mdoc文档系统，您可以通过编辑ns - * .xml文档文件来记录命名空间成员。

有关详细信息，请参阅mdoc file format documentation。