文档生成 - 我应该勾选哪些框？答案

【问题标题】：Documentation Generation - What boxes should I aim to tick?文档生成 - 我应该勾选哪些框？
【发布时间】：2011-04-18 00:34:52
【问题描述】：

我正在考虑要求我的团队为即将到来的一些重大项目更彻底地记录他们的代码并减少生活中的痛苦，我正在转向 XML 文档生成器，例如 Sandcastle、Doxygen 或 @987654323 @。

在评估最佳选择时，我应该牢记哪些主要考虑因素以及哪些经验导致您做出特定决定？

【问题讨论】：

【解决方案1】：

对我来说，主要考虑因素是：

我发现 Doxygen 可以做到这一切。 我们的工作流程如下：

然后，Doxygen 将从代码中提取所有 XML 文档，过滤它以仅包含我们想要的类和方法，并应用我们为它预先制作的 CSS 样式。我们的最终结果是一个内部 wiki，它看起来像我们想要的那样，并且不需要编辑。

额外：我们的所有项目都在各种 git 存储库中。我们将所有这些下拉到一个根文件夹并从该根文件夹生成文档..

有兴趣了解其他人如何进一步实现自动化......？

【讨论】：

【解决方案2】：

比起更多的文档，我更喜欢更好的代码来减轻我的生活痛苦，但我更喜欢场景和单元测试以及高级架构描述。

[编辑] 编写和更新文档需要花费时间和金钱。 JavaDoc 样式文档对同时可见的代码量有严重的不利影响，对于使用代码的开发人员来说可能是一个好主意，但对于编写它的人来说却不是。

【讨论】：

嗯？我也相信可读的代码，但在我当前的项目中，我们有数百个小部件。为什么我要挖掘源代码来找到它们，然后必须阅读源代码来破译它们的作用？一个带有小部件图片的简单列表会很棒。但不幸的是，我们没有文档，现在这是一场噩梦。文档摇滚。
好吧，然后编写一些代码来生成所有小部件的列表。这听起来很简单。
@Stephans：听起来，是的 :) 但它是 6 年前编写的定制引擎。没有什么是简单的。