This question & its answers are useful but not sufficient for my problem.

My Question is if I want to add a javadoc as @Deprecated As of version x.y, replaced by {@link SomeClass} in my current file's javadoc then what should be the version no. in place of x.y ??

Let my current version is 1.2 & after CVS checkin it will be 1.3

  • please provide some web links if possible.. – Soumyadip Das Feb 7 '13 at 4:58
  • 4
    Version here is not referring to your version control system (which are usually referred to as "revisions", not "versions"), but to product release versions. When you deprecate a class, the version x.y should be the version of the first release that introduces the deprecated annotation. – Nate W. Feb 7 '13 at 5:01

Nobody except you cares about the CVS revision numbers; they're an internal artifact of the mechanism you use (if you used Git instead, the revision IDs would be entirely different and without obvious sequence).

Instead, you should define versions in terms of releases where you say “this is a configuration of the code that it makes sense to use as a whole”, and it is those versions that you should refer to in documentation, especially for things like deprecation notices. After all, it is those versions that consumers of the API — the people who will be the consumers of the deprecation notices, and the software they create — will see. In terms of your revision control system, release versions are the sort of thing that it is usually best to model with a tag or label.

If you've not yet done a release, you don't need to deprecate anything. If you've got a release in the past, the deprecation notice should mention the next release version. (It shouldn't mention the version that's just released though; that should be regarded as a static artifact.)

|improve this answer|||||

It sounds like you're using the version control revision as part of your version number. As long as your VCS revision number increments (CVS's does) this isn't a terrible idea.

That said, you should have at least a couple of higher-order numbers in your revision number.

e.g. <major version>.<sprint number>.<CVS revision number>

Instead of <major version>.<CVS revision number>

That way, you can just give the <major version>.<sprint number> part in the javadoc comments - they supercede the CVS revision number anyway. If you don't use sprints, you can just use some arbitrary number that increments whenever you change the API, or for each new feature.

|improve this answer|||||

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.