命名空间的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项目。 在“ 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

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

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

Answer 7

不能在名称空间上添加注释。

http://ndoc.sourceforge.net/content/documenters.htm上的UseNamespaceDocSummaries