文档生成 - 我应该打算选择哪些方框？

Question

我正在考虑要求我的团队为一些重要的即将开展的项目更彻底地记录他们的代码，并让生活变得更加痛苦，我正在转向XML文档生成器，例如Sandcastle，{{3} }或Doxygen。

在评估最佳选择时，我应该记住哪些关键因素以及哪些经验可以让您做出特定的决定？

Answer 1

对我来说，关键考虑因素是：

1. 完全自动化：它可以以这样的方式进行设置 不需要外面的工作 创建或编辑文档。

2. 完全风格化：文档可以完全设置样式 它在wiki或pdf中看起来很棒 在它生成之后。我应该 能够改变颜色，字体大小， 布局等

3. 良好过滤：我可以只选择我想要的项目吗？ 产生。我应该可以 过滤命名空间，文件类型， 课程等。

4. 自定义：我可以包含页眉，页脚，自定义元素， 等

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

1. 开发人员对代码进行了更改

2. 他们更新刚刚更改的代码正上方的文档标记

3. 我们点击生成按钮

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

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

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

Answer 2

1. 谁为文档付费？为什么？ （系统足够稳定，是否增加了足够的价值）
2. 谁会阅读它，为什么她没有使用更有效的沟通渠道？ （如果大致正确的时间/地点距离）
3. 谁将保持最新状态。
4. 你什么时候摧毁它？ （如果在过去三个月内没有阅读或更新，则自动进行？）

我更喜欢更好的代码，让我的生活更少痛苦，而不是更多的文档，但我喜欢的场景＆amp;单元测试和高级架构描述。

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