.Net 项目 (Sandcastle) 上的命名空间文档？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/156582/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Namespace documentation on a .Net project (Sandcastle)?
提问by Ben
I started using Sandcastlesome time ago to generate a Documentation Website for one of our projects. It's working quite well but we've always only written documentation for classes, methods, properties (...) in our project and had completely separate documentation for the overall project and project parts/modules/namespaces. It would be nice if I could merge that documentation together and add respective documentation to the generated helper files but I can't figure out how to do it.
我前段时间开始使用Sandcastle为我们的一个项目生成一个文档网站。它运行良好，但我们始终只为项目中的类、方法、属性（...）编写文档，并且为整个项目和项目部件/模块/命名空间提供完全独立的文档。如果我可以将这些文档合并在一起并将相应的文档添加到生成的帮助文件中，那就太好了，但我不知道该怎么做。
Just adding comments to the namespace declaration doesn't seem to work (C#):
仅向命名空间声明添加注释似乎不起作用（C#）：
/// <summary>
/// My short namespace description
/// </summary>
namespace MyNamespace { ... }
Does anyone know how to do this? I know it's possible somehow and it would be really nice to have... :)
有谁知道如何做到这一点？我知道以某种方式是可能的，拥有......真的很棒：)
回答by Tuinstoelen
Sandcastle also supports the ndoc-style namespace documentation, which allows you to stick the documentation in the source files:
Sandcastle 还支持 ndoc 样式的命名空间文档，它允许您将文档粘贴在源文件中：
Simply create a non-public class called NamespaceDoc in the namespace you want to document, and the xml doc comment for that class will be used for the namespace.
只需在要记录的命名空间中创建一个名为 NamespaceDoc 的非公共类，该类的 xml doc 注释将用于命名空间。
Adorn it with a [CompilerGenerated] attribute to prevent the class itself from showing up in the documentation.
用 [CompilerGenerated] 属性装饰它以防止类本身出现在文档中。
Example:
例子：
namespace Some.Test
{
/// <summary>
/// The <see cref="Some.Test"/> namespace contains classes for ....
/// </summary>
[System.Runtime.CompilerServices.CompilerGenerated]
class NamespaceDoc
{
}
}
The work item in SandCastle is located here.
SandCastle 中的工作项位于 此处。
回答by Davy Landman
If you use Sandcastle Help File Builderthere is a dialog to enter the Namespace summaries. (Apparently also support for defining a specific class, but I wouldn't prefer it..)
如果您使用Sandcastle 帮助文件生成器，则会有一个对话框用于输入命名空间摘要。（显然也支持定义一个特定的类，但我不喜欢它......）
From the feature list:
从功能列表：
Definition of project summary and namespace summary comments that will appear in the help file. You can also easily indicate which namespaces to include or exclude from the help file. Support is also included for specifying namespace comments via a NamespaceDoc class within each namespace.
将出现在帮助文件中的项目摘要和命名空间摘要注释的定义。您还可以轻松地指明要在帮助文件中包含或排除哪些名称空间。还支持通过每个命名空间内的 NamespaceDoc 类指定命名空间注释。
回答by Rinat Abdullin
Use Sandcastle Help File Builder. It allows to specify namespace descriptions in the XML project file
使用Sandcastle 帮助文件生成器。它允许在 XML 项目文件中指定命名空间描述
Example:
例子：
<namespaceSummaryItem name="System" isDocumented="True">
Generic interfaces and helper classes.
</namespaceSummaryItem>
References:
参考：
- example of Open Source projectthat generates documentation with every build (all scripts are in the trunk).
- That's how the documentation by SHFB looks like on the Web(it is deployed on every forced build)
- 每次构建生成文档的开源项目示例（所有脚本都在主干中）。
- 这就是SHFB 的文档在 Web 上的样子（它部署在每个强制构建中）
.
.
回答by Luis
I know it's an old post, but this may be of help to someone else.
我知道这是一个旧帖子，但这可能对其他人有帮助。
Following this link, you can set a description for the namespaces without the need of adding a non-public class to your project.
按照此链接，您可以为命名空间设置描述，而无需向项目添加非公共类。
To edit the namespace summaries, expand the Summaries section within the Project Properties tab in SHFB. You will see a setting named, "NamespaceSummaries", which initially shows the value, "(None)". Click the setting to select it and a button showing an ellipsis symbol (...) appears. Click this button to display the Namespace Summaries dialog box, pictured below:
要编辑命名空间摘要，请展开 SHFB 中“项目属性”选项卡中的“摘要”部分。您将看到一个名为“NamespaceSummaries”的设置，它最初显示值“(None)”。单击设置以将其选中，然后会出现一个显示省略号 (...) 的按钮。单击此按钮可显示“命名空间摘要”对话框，如下图所示：
回答by user1587804
You cant add references that way - do it via NamespaceDoc.cs instances
您不能以这种方式添加引用 - 通过 NamespaceDoc.cs 实例来添加
i.e
IE
/// <summary>
/// Concrete implementation of see cref="IInterface" using see cref="Concrete"
/// </summary>
class NamespaceDoc
{
}
/// <summary>
/// Concrete implementation of see cref="IInterface" using see cref="Concrete"
/// </summary>
class NamespaceDoc
{
}
回答by JohnKoz
I see documentation for an "External XML Comments Files". Showing a schema like:
我看到了“外部 XML 注释文件”的文档。显示如下模式：
<doc>
<assembly/>
<members>
<member/>
</members>
</doc>
If this is placed in a separate file, what would the extension be (xml/aml) and can this be used in the Visual Studio project?
如果将其放在单独的文件中，那么扩展名是什么 (xml/aml) 并且可以在 Visual Studio 项目中使用它吗？
回答by B Pete
Here is the VB.Net version of the C# code snippet shown in Tuinstoelen's accepted answer.
这是 Tuinstoelen 接受的答案中显示的 C# 代码片段的 VB.Net 版本。
I am leaving this answer for those who find this question vis Google and need the VB version, since there is a gotcha waiting if you try to translate form the C# directly.
我将这个答案留给那些在 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
Note the "Global." prepended to namespace to be documented. At least for my VB project configuration, this was necessary so that the name of the namespace is not nested inside the root namespace, but is the name of the root namespace. Before I prepended the "Global.", the compiler was generating a summary for "TestNamespace.TestNamespace", rather than just "TestNamespace". Given that incorrect info in the compiler generated XML file, SandCastle was not recognizing the summary as belonging to the correct namespace.
注意“全局”。前置到要记录的命名空间。至少对于我的 VB 项目配置，这是必要的，以便命名空间的名称不会嵌套在根命名空间内，而是根命名空间的名称。在我添加“Global.”之前，编译器正在为“TestNamespace.TestNamespace”生成摘要，而不仅仅是“TestNamespace”。鉴于编译器生成的 XML 文件中的信息不正确，SandCastle 无法将摘要识别为属于正确的命名空间。
