问题标签 [code-documentation]

哪个工具更适合“Docbook”或“doxygen”或任何其他工具的 C、C++ 和 Java 代码文档您能告诉我任何其他工具吗？

据我了解，“javadoc”是生成 html 文档的工具的名称，该工具的名称也为 javadoc。至少这就是我一直使用这些词的方式..

但是工具 doxygen 生成的输出叫什么？Doxygen 医生？多西医生？或者别的什么？

（在 C++ 上下文中的问题，如果重要的话）

我正在编写一个 C 库（在 Eclipse 上），我想生成文档页面。我真的很喜欢SUSv4 的 HTML 文档，谁能推荐我一个具有类似输出的工具？

注意：自动文档生成和 Eclipse 插件不是必须的。

首先，在这个问题上，我想远离关于源代码注释是好是坏的争论。我只是想更清楚地理解人们在谈论告诉你为什么、什么或如何的评论时的意思。

我们经常看到诸如“评论应该告诉你为什么；代码本身应该告诉你如何”之类的指导方针。在抽象层面上很容易同意该陈述。然而，人们通常会像教条一样放弃这一点，并离开房间而不做进一步的解释。我已经看到它在很多不同的地方和环境中使用，看起来人们可以就流行语达成一致，但他们似乎完全在谈论不同的事情。

所以，回到这个问题：如果评论应该告诉你为什么，我们在说什么是为什么？这就是为什么那段代码首先存在的原因吗？这是那段代码应该做的吗？如果有人能给出清晰的解释，然后添加一些好的示例，我将不胜感激（实际上并不需要坏的示例，但可以随意添加它们以进行对比）。

请不要立即关闭这个问题，因为它是重复的或有争议的。我努力使它非常客观。关于评论是好是坏有很多问题，但没有人能解决哪些是告诉你为什么的评论的好例子的具体问题。

谢谢，

在我的 Java 应用程序中，我总是注释我的类和方法以表明它们的全部内容。然而，我经常遇到的问题是记录一个完整的过程，该过程分布在几个类中。我需要记录所有部分是如何协同工作的，以便简单地概述某些东西是如何工作的。

我发现有问题的是我在哪里写这个文档。我也可以将它写在一个单独的文件中，例如 Word 文档，但文档往往会与实际代码疏远，并且可能会不同步。另一方面，如果我将它记录在单个 java 代码文件中，那么阅读其中一个依赖类的人很难知道该类如何适应整个过程，除非他们知道我所在的类中的文档写的。一种可能的解决方案是在构成整个过程的每个类中包含一个引用，并将其中一个类指定为文档来源的“主要”类。

还是有更好的替代方法来说明我应该如何做到这一点？

编辑：

例如，您有一个将数据上传到服务器的移动应用程序，然后您将数据从服务器下载到另一台设备。您有一个包含三个组件（发送移动设备、服务器和接收移动设备）的流程。这些都不能真正被认为是“整个数据传输过程的起点，所以在记录这个过程时，这个文档会去哪里？

由于某些原因，我想记录一个 API，但我不想直接在源代码中编写文档，因为它现在已经被广泛使用。我正在寻找一个文档生成器工具，它可以将文档文件作为输入，并且能够从源代码中获取函数原型并检查与文档的一致性。你知道任何可以做到这一点的工具吗？

我在这里找到了一篇很棒的文章：

http://www.codeproject.com/Articles/18204/ASP-NET-controls-to-display-enum-values

我在那里研究它，学到了很多东西，并将它作为一个新的类库合并到我的 Visual Studio 解决方案中。

借用代码并在 Web 应用程序中使用后，将 CodeProject 上的原始文章链接到我的 Visual Studio 解决方案（多个项目）的最佳方式是什么，这样我就可以“收藏”这篇文章以供我和我的团队以后参考成员并感谢提出这个想法的原始开发人员。我的一个想法是 EnumControls 类库中的 AboutBox，但我越想它似乎有点愚蠢（我真的只希望在设计时为我的同事和我未来的漏水大脑提供一些文档）。

有一段时间我们可以使用 -callback 属性而不是 behavior_info/1 来声明行为回调（我认为这更方便）。但是，edoc 应用程序似乎无法发现这样的属性。不过，发行说明建议，此问题已在 0.7.10 版（http://www.erlang.org/doc/apps/edoc/notes.html）中修复。有没有人遇到过类似的问题并且能够克服它？

I am having a function that accepts one string parameter. This parameter can have only one of a few defined possible values. What is the best way to document the same? Should shapeType be defined as enum or TypeDef or something else?

The second part of the problem is that the possible values of shapeType is not known in the file that defines shapeType as whatever you suggest. There are multiple files contributed by several developers who might add to the possible values of shapeType.

PS: Am using jsdoc3

我正在尝试自动化我们的 JS 库中的特定模块，并且卡在我想要定义一组属性的点上（假设一个对象作为类的构造参数）。

如果在一个位置定义了建筑的所有属性，那就太好了。不幸的是，我的代码有许多模块有助于构建属性。可以说，在代码的其他部分（在以后的文件中）导致具有更多属性

如何添加到我之前为WorldPeace函数定义的原始属性集？做一些类似 mixin 或子类化属性的事情会过火！因此，如果我可以简单地注入属性列表定义，那就太好了。