代码之家 › 专栏 › 技术社区 › Ben

.NET项目(Sandcastle)的命名空间文档?

sandcastle documentation .net

Ben · 技术社区 · 16 年前

我开始使用 Sandcastle 一段时间前,为我们的一个项目生成一个文档网站。它工作得很好,但是我们总是只为项目中的类、方法、属性(…)编写文档,并且为整个项目和项目部分/模块/名称空间提供了完全独立的文档。如果我可以将该文档合并在一起,并将各自的文档添加到生成的帮助器文件中,那就太好了,但是我不知道该如何做。

仅仅向命名空间声明添加注释似乎不起作用(c):

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

有人知道怎么做吗?我知道这是有可能的,如果有…:)

6 回复 | 直到 7 年前

Tuinstoelen 16 年前

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.

Davy Landman 16 年前

如果你使用 Sandcastle Help File Builder 有一个对话框用于输入命名空间摘要。(显然也支持定义一个特定的类,但我不喜欢它..

从功能列表:

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

Rinat Abdullin 16 年前

使用 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 (IT) 在每个强制生成上部署)

Luis 9 年前

我知道这是一篇旧文章,但这可能对其他人有所帮助。

Following this link ,您可以为命名空间设置描述,而无需向项目中添加非公共类。

要编辑名称空间摘要,请展开SHFB中“项目属性”选项卡中的“摘要”部分。您将看到一个名为“NamespaceSummaries”的设置,它最初显示值“无”。单击要选择的设置,将出现一个显示省略号(…)的按钮。单击此按钮显示“名称空间摘要”对话框,如下图所示:

user1587804 11 年前

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

即

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

see here

JohnKoz 7 年前

我看到“外部XML注释文件”的文档。显示模式,如:

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

如果将扩展名放在单独的文件中,扩展名是什么(xml/aml),它可以在Visual Studio项目中使用吗?