.Net项目(Sandcastle)上的命名空间文档？

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的工作项目位于 此处.

Answer 2

如果使用Sandcastle帮助文件构建器,则会出现一个对话框,用于输入命名空间摘要.(显然也支持定义一个特定的类,但我不喜欢它..)

从功能列表中:

将显示在帮助文件中的项目摘要和命名空间摘要注释的定义.您还可以轻松指出要在帮助文件中包含或排除的命名空间.还包括通过每个命名空间内的NamespaceDoc类指定命名空间注释的支持.

Answer 3

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

例:

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

参考文献:

• 开源项目的示例, 它为每个构建生成文档(所有脚本都在主干中).
• 这就是SHFB的文档在Web上的样子(它被部署在每个强制构建中)

.