命名空间的 XML 文档

Posted 2023-02-23

【中文标题】命名空间的 XML 文档

【英文标题】：XML-documentation for a namespace

【发布时间】：2010-10-22 01:09:39

【问题描述】：

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

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

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

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

【参考方案1】：

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

编辑： 例如：

namespace Some.Namespace

    /// <summary>
    /// This namespace contains stuff
    /// </summary>
    public static class NamespaceDoc
    
    

【讨论】：

那么，直接命名空间文档？我在每个目录中都放一个吗？对他们每个人发表评论...

是的，将在我的答案中粘贴一个示例。

使用 public 而不是 internal 会导致此类也出现在帮助中，这是不好的。

写入 [System.Runtime.CompilerServices.CompilerGenerated] 属性以防止类显示在文档中。

【参考方案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 文件中编写更大的描述。这样，代码就不会被所有细节弄得杂乱无章，并且易于阅读。

【讨论】：

Iiinteresting... 为什么用“Documentation/*”作为路径？

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

【参考方案3】：

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

【参考方案4】：

如果您使用 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 类以类似的方式维护命名空间组 cmets。下面是一个例子：

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

【参考方案5】：

你可以在 doxygen 中使用：

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

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

【参考方案6】：

不能将 cmets 放在命名空间上。

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

【参考方案7】：

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

更多详情请参阅mdoc file format documentation。