Question

前段时间我开始使用Sandcastle为我们的某个项目生成文档网站。它工作得很好，但我们始终只在项目中编写类，方法，属性（...）的文档，并为整个项目和项目部分/模块/命名空间提供完全独立的文档。如果我可以将这些文档合并在一起并将相应的文档添加到生成的帮助文件中，那将是很好的，但我无法弄清楚如何做到这一点。

只是在命名空间声明中添加注释似乎不起作用（C＃）：

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

有谁知道怎么做？我知道它有可能以某种方式存在......：）

Answer 1

Sandcastle还支持ndoc样式的命名空间文档，它允许您将文档粘贴在源文件中：

只需在要记录的命名空间中创建一个名为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中的工作项位于 here.

Answer 2

如果使用Sandcastle Help File Builder，则会出现一个对话框，用于输入命名空间摘要。（显然也支持定义一个特定的类，但我不喜欢它。）

从功能列表中：

项目摘要和定义命名空间摘要注释出现在帮助文件中。你也可以轻松指出要使用的命名空间包含或排除在帮助文件中。还包括支持通过a指定命名空间注释每个NamespaceDoc类命名空间。

Answer 3

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

示例：

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

参考文献：

example of Open Source project 用它生成文档每个构建（所有脚本都在躯干）。

那是how the documentation by SHFB looks like on the Web（它部署在每个强制构建上）

Answer 4

我知道这是一个老帖子，但这可能对其他人有帮助。

Following this link，您可以设置名称空间的描述，而无需向项目添加非公共类。

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

Answer 5

你不能通过这种方式添加引用 - 通过NamespaceDoc.cs实例

来实现

即

/// <summary> /// Concrete implementation of see cref="IInterface" using see cref="Concrete" /// </summary> class NamespaceDoc { }

see here

Answer 6

我看到了“外部XML评论文件”的文档。显示如下的架构：

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

如果将它放在一个单独的文件中，扩展名是什么（xml / aml）并且可以在Visual Studio项目中使用它？

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

注意“全局”。放在要记录的名称空间之前。至少对于我的VB项目配置而言，这是必需的，以便名称空间的名称不嵌套在根名称空间内，而是根名称空间的名称。在添加“ Global。”之前，编译器将为“ TestNamespace.TestNamespace”生成摘要，而不仅仅是“ TestNamespace”。鉴于编译器生成的XML文件中的错误信息，SandCastle无法将摘要识别为属于正确的名称空间。

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

7 个答案: