2

Similarly to how I can specify the minimum compatible Java version using the @since tag, I'd like to specify in my JavaDoc the maximum compatible version (e.i. indicate that my class is only compatible with versions prior to Java 9).

I've seen @version used to specify the compiler version, but a lot of Java code is forwards compatible so I'm not sure if this would work for specifying a bound. I've also seen people use @deprecated with a message saying "removed in Java 9." I don't want to deprecate the class because for the time being it is only intended to be used with Java 8.

Obviously, I can simply leave a note in the JavaDoc comment itself. But my curiosity got the better of me. Is there a JavaDoc tag I can use for this purpose?

Cardinal System
  • 2,749
  • 3
  • 21
  • 42
  • 1
    "I don't want to deprecate the class because for the time being it is only intended to be used with Java 8." Isn't that what deprecation is? – Sweeper May 13 '22 at 13:38
  • You can write your own tags. Refer to [How to create custom javadoc tags?](https://stackoverflow.com/questions/2677564/how-to-create-custom-javadoc-tags) Alternatively, forget the tag and just write a note in the _javadoc_ comments, e.g. **NOTE: Only compatible with JDK versions up to 8.** – Abra May 13 '22 at 13:43
  • @Sweeper I've always had the impression that deprecation is solely used to encourage use of one thing in place of another, to discourage use of something which will be removed in the future, or to discourage for other purposes. Is my understanding incorrect? I do not want to discourage use of this at all. I just want to prevent team members using later versions of Java from attempting to use my dependency. – Cardinal System May 13 '22 at 13:46
  • @Abra I did not know that you can create custom tags. This is very interesting. As for the other half of your comment, it was my original plan to use regular javadoc comments, but I got curious and wanted to see if there's a better way of doing this. – Cardinal System May 13 '22 at 13:47
  • 1
    "I just want to prevent team members user later version of Java from attempting to use my dependency." Your entire dependency? Then you should probably write this in your dependency's GitHub README or somewhere like that, not hidden in the JavaDoc of a particular symbol... – Sweeper May 13 '22 at 13:50
  • 4
    “to discourage use of something which will be removed in the future”—well that seems to be an exact match, unless you plan to fix your Java 9 incompatibility one day. If you plan to fix it, you have something like a “known issue”, not a “before” version constraint. – Holger May 13 '22 at 13:50
  • @Holger I like your point. It seems that deprecating the type is the best course of action after all. I think an answer with a summary of this comments section would have long-term value for others with similar questions. – Cardinal System May 13 '22 at 13:56

0 Answers0