javadoc 版本控制的优缺点
我想知道是否将 Javadoc 文件提交到我的项目的 SVN 存储库。
我读过有关 SVN 良好实践的内容，包括几个关于 SO 的有趣问题，但还没有专门询问关于 javadoc 处理的问题。
起初，我同意只应该对源代码进行版本控制的论点，并且我认为 javadoc 真的很容易使用 Eclipse 或从 javadoc.xml 例如 ant 文件，但我也想到了以下几点：
- Javadoc 文件是轻量级的、文本编码的，并且可以使用 diff 工具轻松跟踪对这些文件的更改。
- 轻松跟踪 javadoc 的更改似乎很有趣，因为在“公共”javadoc 的情况下，它的任何更改都可能意味着 API 的更改。
- 愿意查看 javadoc 的人不一定想要获取整个项目并对其进行编译，因此将其放入存储库中似乎是一个好主意，可以实现高效的共享/跟踪。
您对此有何看法？请用建设性的、非主观的论据来回答。我有兴趣了解哪些案例场景鼓励 Javadoc 的版本控制，哪些案例让它看起来是一个糟糕的选择。
I am wondering whether or not to commit Javadoc files to my project's SVN repository.
I have read about SVN good practices, including several interesting questions on SO, but none has already been asked specifically on javadoc handling.
At first I was agreeing with the arguments that only source code should be versioned, and I thought that javadoc was really easy do re-build with Eclipse, or from a javadoc.xml ant file for example, but I also thought of these points :
- Javadoc files are light, text-encoded, and changes to these files are easily trackable with diff tools.
- It seems interesting to easily track changes to the javadoc, since in the case of a "public" javadoc, any change of it would probably mean a change in the API.
- People willing to look at the javadoc do not necessarily want to get the whole project and compile it, so putting it in the repo seems as good an idea as another to allow for efficient sharing/tracking.
What are your thoughts about this? Please answer with constructive, non-subjective arguments. I am interested in understanding which case scenarios encourage the versioning of Javadoc, and which make it seem a bad choice.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（4）
反对的一个论点是合并冲突，作为一名前 SVN 用户，我讨厌与 SVN 合并。即使使用 Git，这也只是发生这些问题时要做的另一个工作步骤。如果您在一个更大的团队中，定期合并就是日常工作。
另一个反对的论点是，如果有些人不想要整个源代码树，请将整个项目放在像 Hudson 这样的 CI 系统下，并定期触发 javadoc 的创建，例如提交并将它们发布到某个地方。
我的结论是：不要对 javadocs 进行版本控制。
One argument against would be merge conflicts, and as a former SVN user I hate merging with SVN. Even with Git this is just another step of work to do if those problems occur. And if your in a bigger team regular merges are daily work.
Another argument against would be, if a some people don't want the whole source tree, put the whole project under some CI system like Hudson and trigger the creation of the javadocs on a regular basis, like commits and publish them somewhere.
Conclusio for me is: don't version javadocs.
我最近向版本控制系统添加了一些 javadoc 输出（因为 github 显示了分支
gh_pages作为一个网站，这是将它们放在网络上）。这里的一个问题是 javadoc 将 javadoc 运行的日期/时间放入每个文件中，因此您始终可以从一个 提交下一个。因此，只要您在比较时不设法以某种方式忽略这些注释行，就不要指望能够有一个有用的差异来显示您的版本之间的文档真正发生的变化。
（实际上，由于另一个问题我找到了如何省略时间戳。）
当然，您应该始终能够从旧源的签出中重新生成 javadoc。对于已发布的库，请随其发布已发布版本的 javadoc。
对于您在项目中作为 jar 文件使用的第三方库（或您自己不编译的任何文件），存储与源代码树中使用的版本相对应的 javadoc 可能会很有用（因此也可以进行版本控制） ）， 尽管。 （使用Maven时，通常可以将javadoc jar与库的可运行jar一起下载，因此它不适用。）
I recently added some javadoc output to a version control system (since github shows the contents of branch
gh_pagesas a website, this was the easiest way to put them on the web).One problem here is that javadoc puts in every file the date/time of the javadoc run, so you always have changes to all your files from one commit to the next. So don't expect to be able to have a useful diff which shows you what documentation really changed between your versions, as long as you don't manage to somehow ignore these comment lines when diffing.
(Actually, due to another question I found out how to omit the timestamp.)
And of course, you should always be able to regenerate your javadoc from a checkout of the old sources. And for released libraries, publish the javadoc of the released version with it.
For third party-libraries which you are using inside your project as jar files (or anything that you don't compile yourself) it might be useful to store the javadoc corresponding to the version used inside the source tree (and thus be versioned, too), though. (When using Maven, you usually can download a javadoc jar together with the runnable jar of the library, so then it doesn't apply.)
简短的回答：不，不要对 Javadocs 进行版本控制。
Javadoc 是从您的代码生成的，类似于您的 .class 文件。如果您的 API 发生更改并且您需要发布新版本的文档，您可以随时恢复到该版本（或进行新的签出）并从那里生成 Javadocs。
Short answer: no, don't version your Javadocs.
The Javadocs are generated from your code, analogous to your .class files. If your API changes and you need to release a new version of the docs, you can always revert to that revision (or do a new check out) and generate the Javadocs from there.
我的两分钱...
我不知道有多少次我希望有旧版本的 Javadoc 可用。例如，我可能使用旧版本的第三方库，但该库的 API 文档基于当前代码。如果您使用的是当前代码，那么一切都很好，但如果您使用的是旧版本，javadocs 实际上可能会误导您如何使用相关类。
这可能更多是您分发的库的问题，而不是您自己的内部代码的问题，但这是我一次又一次遇到的问题
My two cents...
I don't know how many times I've WISHED I had old versions of Javadocs available. For example, I may be using an old version of a third-party library, but the API docs for that library are based on the current code. All well and good if you're using the current code, but if you're on an older version, the javadocs could actually mislead you on how to use the class in question.
This is probably more of an issue with libraries you distribute than with your own internal code, but it is something I've run into now and again