将开发人员文档添加到Visual Studio项目的最佳方法

Question

基本上，问题是：我应该在哪里（以及采用哪种格式）存储与我的Visual Studio项目相关的文本开发者文档？

详细说明：XML注释很棒，但它们并不涵盖所有用例。有时，您希望在高级别描述项目的类体系结构，向库中添加使用说明，或者将任何其他类型的消息留给从事此项目的未来几代开发人员。

我想将这些文档作为文件直接添加到Visual Studio项目中，以确保（a）开发人员可以使用它们而无需进一步搜索，并且（b）它们受版本控制（使用相同的svn / git） /无论什么存储库作为源代码）。

目前，我在项目中添加了一个文件夹_Documentation并使用了文本文件，但我不确定这是否是最佳解决方案。 Visual Studio没有自动换行文本 ¹ 的选项，并且在每次更改后手动修复换行符都很烦人。另一方面，Word文档在版本控制方面效果不佳，而TeX在每台开发者PC上设置和教授都太麻烦了。

这是否有完善的最佳实践？

---

¹ 我知道有编辑/高级/自动换行，但这只影响显示，而不影响文件本身。

Answer 1

我遇到了同样的问题 - 只是我注意到我能够添加一个HTML文件。打开后，只需切换到屏幕底部的“设计”。 您可能希望将构建操作从“内容”更改为“无”

由于它是一个硬编码的HTML文档，因此也可以使用内嵌图片（例如图表）

同样出于我的目的（编程指南，架构描述，数据库使用示例）我选择创建一个单独的项目（_Documentation）作为 Windows窗体，因为这将允许我（或者一个新的程序员）有一个运行的例子。

Answer 2

我使用GhostDoc（visual studio插件）来记录我的项目，因为我添加了类，方法，属性等：http://visualstudiogallery.msdn.microsoft.com/46A20578-F0D5-4B1E-B55D-F001A6345748

Answer 3

您可以选择在XML注释中包含大量数据，然后可以使用Sandcastle (site)等工具获取这些数据，并转换为实际的MSDN样式参考站点。

我倾向于使用此方法并使用<para></para>编写长XML注释(MSDN comment tags)（在适当的情况下）以生成段落并解释未来修饰符/开发人员所需的任何模式，业务原因或架构信息。我也用它来举例说明。

一批好的测试（编写良好并命名）也可以真正阐明代码的用途，作为规范。

我希望你的研究可能会提供一些信息：）

Answer 4

XML注释最适合记录特定方法，而不是编写长概念内容的理想选择。长XML注释可能会对代码可读性产生负面影响。

我喜欢Sandcastle的概念主题文档功能，我们可以创建和存储与功能或体系结构相关的概念文档，并将其与代码文档（XML注释）合并。您可以在编写概念主题时使用的标记是可扩展的，这意味着我们甚至可以遵守企业模板。