一个命名空间的XML文档说明

Question

你会为一个命名空间编写 XML 文档吗？如果是，应该如何编写以及在哪里编写？

我认为，如果可能的话，可以创建一个几乎为空的文件，就像这样：

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

}

但这样会有效吗？因为你需要"声明"或者至少在其他所有文件中也使用该命名空间...如果你在同一命名空间的其他地方编写了一个xml文档，会发生什么？ 会被覆盖还是会以某种方式合并？

- Svish

Answer 1

NDoc通过识别每个命名空间中的一个特殊的NamespaceDoc类并使用该类的文档来实现此功能。我没有尝试过，但似乎Sandcastle也支持这个技巧。

编辑： 例如：

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

- Tim Robinson

---

那么，NamespaceDoc 是直接放在文件夹中吗？那我需要每个目录都放一个来针对它们写注释吗？ - Svish

好的，我会在我的回答中粘贴一个例子。 - Tim Robinson

使用"public"而不是"internal"将导致该类在帮助文档中出现，这是不好的。 - Admir Tuzović

编写[System.Runtime.CompilerServices.CompilerGenerated]属性以防止该类显示在文档中。 - Sergio Cabral

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 文件中为帮助文件编写更大的描述。这样，代码不会混杂所有细节，并保持易读性。

- Mikko Rantanen

---

有趣...为什么路径要写成"Documentation/*"？ - Svish

哦，这是一个XPath表达式到_Namespace.xml。可以将所有文档存储在同一个XML文件中，并根据其路径包含这些文档，例如path='Documentation/Namespace/*'等。示例XML使用根标记Documentation/*并且是类特定的，因此路径只包括根标记内的所有内容。 - Mikko Rantanen

Answer 3

Sandcastle帮助文件生成器支持命名空间的注释。打开你的Sandcastle项目，在项目属性窗口中导航到Summaries并单击编辑命名空间摘要按钮。

- Norbert Szenasi

Answer 4

您可以在 Doxygen 中使用以下方式实现：

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

此外，声明您的命名空间在NameSpaces.cs文件中是一个好的实践，并且只在此文件中进行注释。

- Adrian Lopez

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

- MarkusE

Answer 6

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

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

- jonp

Answer 7

命名空间上无法添加注释。

在http://ndoc.sourceforge.net/content/documenters.htm上使用NamespaceDocSummaries

- Kirtan

Answer 8

可以通过创建一个名为Namespaces.cs的文件来在Visual Studio中完成，内容如下：

// This file is inteded to only create the namspace comments.
// Therefore the warnig 'CS1587: XML comment is not placed on a valid language element'
// must be disabled for this file.
#pragma warning disable CS1587

// --------------------------------------------------------------

/// <summary>
/// This namespace implements the IO functionality for MyProduct
/// </summary>
namespace MyCompany.MyProduct.IO { };

// --------------------------------------------------------------
// Restore warning
#pragma warning restore CS1587

- FrankH