c# - 如何将文件夹级文档添加到 C# 程序集中？

Question

我:我是 .NET 平台的新手。

问题

在 Java 中，您可以通过创建 package-info.java 或 package.html 文件并将其存储在包文件夹中，向项目添加包级文档。如何使用 Visual Studio 2010 将等效文档添加到我的 C# 项目中？

背景

我喜欢在我正在处理的源代码项目的包/文件夹级别上下文中编写描述我动机的文档。我已经非常习惯这种使用多种语言(特别是 Java)的工作流程，并且我相信这是记录我的项目的好方法。

Answer 1

C# 会自动将基于 XML 的三斜杠注释转换为智能感知文档。

///<summary>This method does something!</summary>
///<parameter name="p1">The first parameter</parameter>
///<return>true, if the method completed successfully</return>
public bool DoSomething(int p1){
  return p1 > 0;
}

当您将项目编译成类库并在另一个项目中引用它时，上面的内容将自动变成有用的工具提示。此外，C# 编译器可以选择生成一个 XML 文件，其中包含所有这些注释以及 DLL。该 XML 文件可以输入 Sandcastle (如前所述)并作为 MSDN 风格的 API 引用添加到文档项目中。

SandcaSTLe 工具有自己的项目和文档结构，因此，如果您要添加除 XML 生成的 Intellisense 引用之外的任何内容，您需要启动一个副项目。