Eclipse 上单独文件中的 Java 文档

Question

我在实习期间一直在使用 Eclipse，在上次测试中，他们给了我一个要修复的真实项目的样本，整个代码一团糟。尽管有人警告我说，在日常工作中无法负担完整的代码文档，但我还是想努力尝试从现在开始编写的任何代码中做到这一点。

为了清楚起见，我所说的“文档”是任何方法（JavaDoc）之前的注释，它解释了该方法的作用。当我将鼠标悬停在它上面时可以查看它，就像我使用 String 语句时一样。

我知道这些 cmets 在 Java 源代码的一个类中。

但我认为将 Javadoc 留在文件中会破坏我的代码的易读性，所以问题是：有没有办法将这些 Javadoc 文档保存在单独的文件中，在我的代码中删除它们，但当我仍然可见时悬停在我的方法中？

我已经尝试过“生成 Javadoc”，但是由于我在代码中删除了它，所以悬停的东西不再起作用了。

提前谢谢你。

Answer 1

JavaDocs 必须是内联的。当你考虑它时，它是有道理的。如果您要更改方法的签名或行为，并且该方法的文档在其他文件中已关闭，那么您很快就会得到不准确且因此无用的文档。人们会忘记更新它，或者因为麻烦而故意避免这样做。

如果 cmets 的长度让您烦恼，像 IntelliJ 这样的 IDE 将允许您折叠 JavaDocs（和任何其他块）以隐藏它们：

我使用 Eclipse 已经有一段时间了，但我怀疑它是一样的。

“生成 JavaDoc”是一种解析 JavaDoc cmets 并生成 HTML 的方法，可以单独浏览或托管在网页上，just like the classes from the JDK have。

---

顺便说一句，你有志于编写高质量的文档，这真是太好了。世界需要更多这样的开发者。

Answer 2

不，不可能将 Javadoc 放在其他地方。 Javadoc 背后的整个想法是“让我们将文档直接放入源代码中”。

其背后的原因是，对于大多数开发人员来说，这与他们愿意寻找文档的实际代码相距甚远，并且与他们可以费心去写一些东西相距甚远。