.NET 项目的独立文档 - doxygen？ [关闭]

Question

任务

我们希望根据以下标准为我们的 .NET 项目维护一些开发人员文档：

• “文档”，最好用 Markdown 编写，用于提供与一段代码不密切相关的信息（如概述、常见问题解答）。
• 用于代码和 API 文档的标准内联 cmets。因此，我们以类/接口上的标准内联 (XML) cmets 的形式（主要是为了支持 IntelliSense，其次是为了能够生成 API 引用）并希望继续这样做。
• 文档包含在它所记录的内容中；例如如果它是解决方案的概述，那么在解决方案中，如果它是针对项目的，那么在项目的文件中，版本控制方式与代码相同（这样文档与他们记录的内容接近，因此它们不太容易因为过时了，而且这是文档总是“手头”）。
• 能够（从 CI 服务器）为整个项目自动生成可读、已编译的文档，包括 API 的“文档”和内联 cmets。

一个例子

我们有一个项目，它是一个可在第 3 方系统中使用的组件。对于这个项目，我们有以下类型的文档：

• 概述（项目做什么，目标是什么）
• 安装说明
• API 文档
• 版本历史

我们希望我们的开发人员和其他开发人员能够 - 从项目的源代码包中阅读此文档并 - 来自网站。

我们研究过的解决方案

• 使用 wiki（我们尝试过 Confluence）：这对于“文档”类型的文档（如概述或安装说明）很有用，但它独立于项目本身存在。这是另一个需要维护的系统，因为在开发时它不在眼前，它很快就会过时。此外，以某种方式将自动生成的 API 文档集成到其中也是一项任务。
• 使用 Markdown 文件并将它们存储在代码中：这很简单，文档始终在手边，并且与文档内容接近；但是，我们不知何故需要从这些文件和源文件的内联文档中生成一个可发布的 Web 包。

到目前为止，doxygen 看起来像是能够提供所有这些的解决方案。你同意吗？

见“How to include custom files in doxygen”。

Answer 1

总的来说，这正是我目前正在做的事情，而且我正在使用 Doxygen。

但是，恐怕我对 .NET 一无所知。我正在处理的项目是一个 Java 包，但包括从源代码中提取的 API 文档、用户指南、发布记录和诸如弃用之类的东西。

唯一超出我们范围和在您范围内的是安装指南，但这实际上只是因为开发人员只能在安装后阅读它。

我们让 Jenkins CI 针对每次更改构建文档。

“描述性”文本全部用 Markdown 编写，Doxygen 处理得相当好。

缺点：如果您熟悉 Doxygen 处理源代码文本分组的方式，您可能会感到困惑，这些命令无法在 Markdown 中对文本块进行分组。还有一些其他特定的奇怪之处，但如果您浏览我自己关于该主题的问题（here、here 和 here），您可能会发现其中的大部分。

优点：（我们发现您没有提到的有用的东西）

1. 我们还可以解析 Java API 中的“doxygen”标记，以创建 IDE （例如 Eclipse）可以使用的 javadoc。这确实意味着我们必须将自己限制为 API 文档中的 javadoc 样式命令，但这并不是一个很大的限制。

2. 我们在 doxygen 的“构建开关”下为您的 开发人员提供了一份关于如何编写手册文档的手册（好吧，这有点递归！）。这提供了推荐使用的命令子集，以及是否（根据口味）您是否希望人们使用 doxygen @subsection 或 Markdown ## 作为标题等。

希望对您有所帮助。

我建议你尝试一下；试用您需要的每种类型的文档部分的样本，看看它是否会完成您需要的整套功能。没有什么比记录 90% 更烦人了，然后发现它不会做最后 10%。