一个 .Net 项目（Sandcastle）的命名空间文档？

Question

我一段时间以前开始使用Sandcastle为我们的一个项目生成文档网站。它运行得非常好，但我们一直只为项目中的类、方法、属性等编写文档，并分别为整个项目和项目部分/模块/命名空间编写完全不同的文档。如果我可以将这些文档合并在一起，并向生成的帮助文件添加相应的文档，那就太好了，但我不知道该如何操作。

仅向命名空间声明添加注释似乎行不通（C#）:

/// <summary>
/// My short namespace description
/// </summary>
namespace MyNamespace { ... }

有人知道如何做到这一点吗？我知道这是可能的，而且拥有这样的功能真的很不错...:)

- Ben

Answer 1

Sandcastle还支持ndoc-style的命名空间文档，这允许您将文档粘贴到源文件中：

在要文档化的命名空间中创建一个名为NamespaceDoc的非公共类，该类的xml doc注释将用于该命名空间。

使用[CompilerGenerated]属性进行修饰，以防止该类本身出现在文档中。

例如：

namespace Some.Test
{
    /// <summary>
    /// The <see cref="Some.Test"/> namespace contains classes for ....
    /// </summary>

    [System.Runtime.CompilerServices.CompilerGenerated]
    class NamespaceDoc
    {
    }
}

在SandCastle中的工作项可以在这里找到。

- Tuinstoelen

---

我更喜欢这个方法，而不是污染配置文件 :| 而且在项目中更容易看到。 - Groxx

我使用Visual Studio的插件，这真是一项福祉。谢谢！ - Hilydrow

同意@Groxx的观点。我认为可见性也适用于此方法，而不仅仅适用于Sandcastle项目的设置。 - krillgar

这种方法很有效。我发布了VB.Net版本的代码作为单独的答案，因为在C#到VB的转换中有一个非常不明显（至少对我来说）的问题。 - B Pete

Answer 2

如果您使用Sandcastle Help File Builder，则有一个对话框可输入名称空间摘要。(显然还支持定义特定类，但我不太喜欢..)

来自功能列表:

定义项目摘要和名称空间摘要注释，它们将出现在帮助文件中。您还可以轻松地指示要包含或排除哪些名称空间以及为通过每个名称空间中的NamespaceDoc类指定名称空间注释提供支持。

- Davy Landman

---

选项在项目属性 > 注释 > 命名空间摘要 中。 - Richard Garside

这在最新版本（目前为1.9.3.0）中已经改变为项目属性 > 摘要 > 命名空间摘要。 - Ant Swift

旧话题，但也许对某些人有帮助。它在版本17.1.28.0中也有效。感谢这个提示。 - Piotr Knut

Answer 3

使用 Sandcastle Help File Builder。它允许在XML项目文件中指定命名空间描述。 示例：

<namespaceSummaryItem name="System" isDocumented="True">
    Generic interfaces and helper classes.
</namespaceSummaryItem>

参考资料:

• 一个开源项目的示例，每次构建都会生成文档（所有脚本都在主干中）。
• SHFB文档在Web上的呈现方式（它会在每次强制构建时部署）。

- Rinat Abdullin

---

上面示例的链接已更改，现在可以在此处找到：http://lokad.svn.sourceforge.net/viewvc/lokad/Platform/Trunk/SafetyStockCalc/Lokad.SafetyStock.shfb - Marc Climent

Answer 4

我知道这是一篇旧文章，但这可能对其他人有所帮助。通过点击此链接，您可以为命名空间设置描述，而无需向项目添加非公共类。

要编辑命名空间摘要，请在SHFB的“项目属性”选项卡中展开“摘要”部分。您将看到一个名为“NamespaceSummaries”的设置，最初显示值“(None)” 。单击该设置以选择它，然后会出现一个显示省略号(...)的按钮。单击此按钮以显示下面图片所示的“命名空间摘要”对话框：

- Luis

Answer 5

您不能以这种方式添加引用 - 请通过NamespaceDoc.cs实例进行操作

i.e

/// <summary> /// 使用 see cref="Concrete" 具体实现了 see cref="IInterface" 的实现
/// </summary> class NamespaceDoc { }

点击此处查看

- user1587804

Answer 6

我看到了关于“外部XML注释文件”的文档，其中显示了一个类似于以下的模式：

<doc>
    <assembly/>
    <members>
        <member/>
    </members>
</doc>

如果将此内容放在单独的文件中，该文件的扩展名应该是什么（xml/aml），并且是否可以在Visual Studio项目中使用？

- JohnKoz

Answer 7

这是Tuinstoelen所接受的答案中所示C#代码片段的VB.Net版本。

我留下这个答案是为了那些通过Google找到这个问题并需要VB版本的人，因为如果你尝试直接从C#翻译，会有一个陷阱等着你。

Namespace Global.TestNamespace
    ''' <summary>
    ''' The <see cref="TestNamespace"/> namespace contains classes for ....
    ''' </summary>
    <System.Runtime.CompilerServices.CompilerGeneratedAttribute()>
    Class NamespaceDoc
    End Class
End Namespace

请注意在要记录的命名空间前面添加“Global.”。至少对于我的VB项目配置来说，这是必需的，以便命名空间的名称不会嵌套在根命名空间内，而是根命名空间的名称。在我添加“Global.”之前，编译器为“TestNamespace.TestNamespace”生成了摘要，而不只是“TestNamespace”。由于编译器生成的XML文件中存在不正确的信息，SandCastle无法将摘要识别为属于正确的命名空间。

- B Pete