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 参考，您还需要启动一个辅助项目。

Answer 2

.NET 中的重点有点不同，它对生成 IntelliSense 信息有很好的支持。文档触手可及。相信你用VS一段时间就熟悉了，查一下“xml文档”。

NDoc 曾经涵盖离线文档，但支持它的人退出了他的项目。Sandcastle 项目弥补了这一不足。顺便说一句，这些天似乎也有点滞后。