C# 命名空间的 XML 文档

XML-documentation for a namespace

提问by Svish

Would you write xml-doc for a namespace? And if yes, how and where?

您会为命名空间编写 xml-doc 吗？如果是，如何以及在哪里？

I would think, if it is possible, maybe an almost empty file like this:

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

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

}

But will that work? Since you... "declare", or at least use the namespace in all the other files as well... and what would happen if you wrote an xml-documentation thing somewhere else on the same namespace? Would one be gone? Or would they be merged somehow?

但这会奏效吗？既然你……“声明”，或者至少在所有其他文件中也使用命名空间……如果你在同一个命名空间的其他地方写了一个 xml 文档，会发生什么？一个会消失吗？或者他们会以某种方式合并？

采纳答案by Tim Robinson

NDoc supports this by recognising a special NamespaceDocclass located in each namespace, and using the documentation from that. I haven't tried it, but Sandcastle appears to support the same trick.

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

Edit:For example:

编辑：例如：

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

回答by Kirtan

It is not possible to put comments on namespaces.

不能对命名空间发表评论。

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

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

回答by Mikko Rantanen

Sandcastle does not support the NamespaceDoc directly, but if you use Sandcastle Help File Builderyou can use the NamespaceDoc class mentioned by Tim.

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 also extends the syntax slightly and allows embedding code examples straight from code files. An example _Namespace.xml:

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>

Including documentation in XML file allows you to write short summary in code and larger description in a separate XML file for the help file. This way the code isn't cluttered with all the details and remains easily readable.

在 XML 文件中包含文档允许您在代码中编写简短的摘要，并在单独的 XML 文件中为帮助文件编写更大的描述。这样，代码就不会被所有的细节弄得杂乱无章，并且仍然易于阅读。

回答by jonp

If using Mono's mdocdocumentation system, you can document namespace members by editing the ns-*.xml documentation files.

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

See the mdoc file format documentationfor more details.

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

回答by Norbert Szenasi

Sandcastle Help File Builder supports comments on namespaces. Open your Sandcastle project. In Project Propertieswindow navigate to Summariesand click on the Edit Namespace Summariesbutton.

Sandcastle 帮助文件生成器支持对命名空间的注释。打开您的 Sandcastle 项目。在Project Properties窗口中导航到Summaries并单击Edit Namespace Summaries按钮。

回答by Adrian Lopez

You can do it in doxygen using:

你可以在 doxygen 中使用：

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

Also, it's a good practice to declare your namespaces in a NameSpaces.cs file, and comment them only in this file.

此外，在 NameSpaces.cs 文件中声明命名空间是一种很好的做，并且仅在此文件中对其进行注释。

回答by MarkusE

If you use Sandcastle and its "Help File Builder" you can document namespaces and Namespace-Groups using the following Code in your Projects:

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

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

If the project has namespace grouping enabled, you can also maintain the namespace group comments using a NamespaceGroupDoc class in a similar fashion. The following is an example:

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

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

To keep the NamespaceDoc class from appearing in the help file, leave off the public keyword and mark it with a CompilerGenerated attribute.

要防止 NamespaceDoc 类出现在帮助文件中，请去掉 public 关键字并使用 CompilerGenerated 属性对其进行标记。

For Reference see here: https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

参考见这里：https: //ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm