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

Question

前段时间我开始使用Sandcastle为我们的一个项目生成一个文档网站。它运行良好，但我们一直只为项目中的类、方法、属性（...）编写文档，并且为整个项目和项目部分/模块/命名空间提供完全独立的文档。如果我可以将该文档合并在一起并将相应的文档添加到生成的帮助文件中，那就太好了，但我不知道该怎么做。

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

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

有谁知道如何做到这一点？我知道这是有可能的，如果能拥有... :)

score 80 · Accepted Answer

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

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

用 [CompilerGenerated] 属性装饰它，以防止类本身出现在文档中。

例子：

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

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

SandCastle 中的工作项位于此处。

score 19 · Accepted Answer

如果您使用Sandcastle 帮助文件生成器，则会出现一个对话框来输入命名空间摘要。（显然也支持定义一个特定的类，但我不喜欢它..）

从功能列表中：

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

score 8 · Accepted Answer

使用Sandcastle 帮助文件生成器。它允许在 XML 项目文件中指定命名空间描述

例子：

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

参考：

开源项目的示例，它在每次构建时生成文档（所有脚本都在主干中）。
这就是SHFB 的文档在 Web 上的样子（它部署在每个强制构建中）

.

score 4 · Accepted Answer

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

在此链接之后，您可以为命名空间设置描述，而无需向您的项目添加非公共类。

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

score 1 · Accepted Answer

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

IE

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

看这里

score 0 · Accepted Answer

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

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

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

score 0 · Accepted Answer

这是 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 - .Net 项目（Sandcastle）的命名空间文档？

7 回答 7

Related

Reference