版本控制Java文档的优缺点

Question

6

我在考虑是否要将Javadoc文件提交到我的项目的SVN存储库中。

我已经阅读了关于SVN最佳实践的文章，包括一些有趣的Stack Overflow问题，但还没有特别讨论过Javadoc的处理方式。

起初，我同意只应该对源代码进行版本控制的论点，而且我认为使用Eclipse或者从一个 ant文件中重建Javadoc非常容易，但是我也想到了这些观点：

您对此有何想法？请用建设性的、非主观的论点回答。我有兴趣了解哪些情况鼓励对Javadoc进行版本控制，哪些情况使其看起来不是一个好选择。

- Dunaril

4个回答

2

最近我把一些javadoc输出添加到了版本控制系统中（因为GitHub将分支gh_pages的内容展示为网站，这是最简单的将它们放到网络上的方法）。

一个问题在于，javadoc会在每个文件中插入运行javadoc时的日期/时间，因此从一个提交到下一个，你总会看到对所有文件的更改。所以，如果你不设法忽略这些注释行进行差异比较，就别指望能够看到在版本之间实际改变的文档部分。（实际上，由于另一个问题我发现了如何省略时间戳。）

当然，您应该始终能够从旧源代码的检出中重新生成您的javadoc。对于已发布的库，请将发布版本的javadoc一起发布。

对于作为jar文件（或任何您不自己编译的内容）在项目中使用的第三方库，将与源代码树中使用的版本相对应的javadoc存储起来（因此也会有版本控制）可能很有用。（当使用Maven时，通常可以与可运行的库一起下载javadoc jar，因此不适用。）

- Paŭlo Ebermann

1

短答案：不要对您的Javadocs进行版本控制。

Javadocs是从代码生成的，类似于您的.class文件。如果您的API更改并且需要发布文档的新版本，则始终可以还原到该修订版（或进行新的检查）并从那里生成Javadocs。

- Babak Naffas

1

我的两分钱意见...

我不知道自己有多少次希望能够获得旧版的Javadocs。例如，我可能正在使用一个旧版本的第三方库，但是该库的API文档是基于当前代码的。如果你正在使用当前的代码，那么一切都很好，但是如果你在旧版本上，则Javadocs实际上可能会误导你如何使用相关的类。

这可能更多地涉及到你发布的库，而不是你自己的内部代码，但这确实是我偶尔遇到的问题。

- Gordon

虽然在这种情况下，@Dunaril正在处理内部代码。使用版本控制，他们将始终能够生成与代码库相对应的确切Javadocs文档。 - Babak Naffas

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Nick Weaver · Accepted Answer

有人反对版本化Javadocs的一个理由是合并冲突。作为一名曾经使用SVN的用户，我非常讨厌用SVN进行合并。即使使用Git，如果出现这些问题，这仍然是要完成的另一步工作。而且，如果你在一个更大的团队中，定期合并是日常工作。

另一个反对意见是，如果有些人不想要整个源代码树，可以将整个项目放在像Hudson这样的CI系统下，并定期触发创建Javadocs，就像提交一样，并将它们发布到某个地方。

对我来说，结论是：不要对Javadocs进行版本控制。