文档生成 - 我应该勾选哪些框？
我正在考虑要求我的团队为即将到来的一些主要项目更彻底地记录他们的代码，并让生活少一点痛苦，我正在转向 XML 文档生成器，例如 Sandcastle、Doxygen 或 Box Live Documenter。
在评估最佳选择时我应该牢记哪些关键考虑因素以及哪些经验促使您做出特定决定？
I'm looking at requiring my team to document their code more thoroughly for some major upcoming projects and to make life a little less painful, I am steering towards XML documentation generators such as Sandcastle, Doxygen or Box Live Documenter.
What are the key considerations I should keep in mind when evaluating the best option and what experiences have led you to a particular decision?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（2）
对我来说，关键的考虑因素是：
完全自动化：是否可以以这样的方式设置，以便几乎
无需外出工作
创建或编辑文档。
完全样式化：文档可以完全样式化吗？
它在 wiki 或 pdf 中看起来很棒
生成后。我应该是
能够改变颜色、字体大小、
布局等。
良好的过滤：我可以只选择我想要的项目吗
生成的。我应该能够
过滤命名空间、文件类型、
类等。
自定义：我可以包含页眉、页脚、自定义元素吗？
等等。
我发现 Doxygen 可以做到这一切。 我们的工作流程如下：
开发人员对代码进行更改
他们更新了刚刚更改的代码上方的文档标签< /p>
Doxygen 然后将从代码中提取所有 XML 文档，对其进行过滤以仅包含我们想要的类和方法，并应用我们想要的 CSS 样式已经预先做好了准备。我们的最终结果是一个内部 wiki，它看起来像我们想要的那样，并且不需要编辑。
额外：我们的所有项目都位于各种 git 存储库中。我们将所有这些内容拖放到一个根文件夹中，并从该根文件夹中生成文档。
有兴趣了解其他人如何进一步实现自动化吗？
For me the key considerations would be:
Fully automated: Can it be set up in such a way so that pretty much
no outside work is required to
create or edit the documentation.
Fully styled: Can the documentation be fully styled so
that it looks great in a wiki or pdf
after it’s generated. I should be
able to change colors, font sizes,
layouts, etc.
Good Filtering: Can I select only the items I want to be
generated. I should be able to
filter the namespaces, file types,
classes, etc.
Customization: Can I include headers, footers, custom elements,
etc.
I found Doxygen could do all of this. Our workflow is as follows:
Developer makes a change to the code
They update the documentation tags right above the code they just changed
Doxygen will then extract all the XML documentation from the code, filter it to only include the classes and methods we want, and apply the CSS styling we’ve pre-made for it. Our end result is an internal wiki that looks the way we want, and doesn’t require editing.
Extra: We have all our projects in various git repositories. We pull all these down to one root folder and generate the docs form this root folder..
Would be interested to know how others are automating even further..?
（如果时间/地点的距离大部分正确）
我更喜欢更好的代码来让我的生活不那么痛苦，而不是更多的文档，但我喜欢场景和内容。单元测试和高级架构描述。
[编辑] 文档的编写和更新需要时间和金钱。 JavaDoc 风格的文档对同时可见的代码量有严重的不利影响，对于使用代码的开发人员来说可能是一个好主意，但对于编写代码的开发人员来说却不是。
(if correct mostly distance in time/place)
I mostly prefer better code to make my life less painful, over more documentation, but I like scenario & unit tests and a high level architecture description.
[edit] Documentation costs time and money to write and keep up to date. JavaDoc style documentation has a serious detrimental effect on the amount of code simultaneously visible and might be a good idea for the developers using the code, but not for those writing it.