JDK-8072583 : javac should no longer treat @deprecated javadoc tag as indicating formal deprecation
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javac
  • Affected Version: 9
  • Priority: P4
  • Status: Open
  • Resolution: Unresolved
  • Submitted: 2015-02-05
  • Updated: 2024-10-10
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
tbdUnresolved
Related Reports
Relates :  
JDK-8141234 - javac/javadoc should warn if @Deprecated annotation is present but @deprecated javadoc tag is missing
Relates :  
JDK-8164073 - Javac should unconditionally warn if deprecated javadoc tag is used without @Deprecated annotation
Relates :  
JDK-8068626 - Add javac lint warning when the @Deprecated annotation is used where it is a no-op
Description
Prior to Java SE 5.0, deprecation was formally indicated using the "@deprecated" javadoc tag. Java SE 5.0 instead defined the java.lang.Deprecated annotation type for that purpose, with the @deprecated tag being retained to provide helpful suggestions on what to do instead of using the deprecated API.

However, javac has continued to treat the @deprecated javadoc tag as indicating deprecation and issues the same warning messages as if @Deprecated were used.

At least for source levels of 9 and above, I'd recommend javac

1) Stop treating @deprecated as an indication of deprecation
2) Issue a warning message if @deprecated is used on a declaration that is not also @Deprecated
Comments
I think we need to work through some different scenarios to figure out where we want to end up. First is the @deprecated tag vs @Deprecated annotation. If there is a tag without an annotation, making the warning mandatory is fine. Changing that situation to silently remove the deprecated semantics seems like a step in the wrong direction. I'd suggest either a) in a subsequent release, upgrading the warning to an error; or b) having the tag automatically synthesize an annotation if one isn't present. Second is the deprecated classfile attribute vs. the annotation. When javac is reading an already-compiled class file, it honors either the attribute or an annotation. I think that behavior has to stay. But when creating a classfile, maybe we should consider having javac stop emitting the classfile attribute, for classfile versions greater than some value. (9? 10?) That seems consistent with my suggestion b) above.
17-08-2016
Via JDK-8164073, I'll handle the unconditional warning behavior (i.e not just under -Xlint:dep-ann), The present ticket can be worked on for a future release.
16-08-2016
FWIW, roughly 290 warnings get emitted about missing @Deprecated annotations while building openJDK with an enhanced compiler. None of these result in build breakage as these presumably originate from component(s) that are built without -Werror
12-08-2016
I have a fix available just for making the warning unconditional (while still honoring any attempts at suppression). Once the discussion concludes, I will split this into two tickets as needed.
12-08-2016
Should this be one of those multi-release transitions? In JDK 9 we unconditionally warn about the use of @deprecated without @Deprecated, but still generate the attribute. In JDK 10+, we unconditionally warn about the use of @deprecated without @Deprecated, but don't generate the attribute. We should continue to honor the use of the Deprecated classfile attribute for older classfile versions (for always), but start ignoring it for newer (v54+?) versions.
11-08-2016
The change to the warnings behavior is fine. I think that as of -source 9, changing the @deprecated javadoc tag not to make the API element actually deprecated, is surprising, incompatible, and possibly dangerous behavior. If you have an old library with deprecated elements (@deprecated javadoc tag but not @Deprecated annotated), and you recompile that library with Java 9, you'll get the additional warnings. You might not immediately grasp the significance of the new warnings. But the library binary that results no longer has those API elements deprecated, meaning that they'll appear to library clients as having been un-deprecated. I agree with the sentiment of trying to transition away from the @deprecated javadoc tag in the absence of the @Deprecated annotation, but this doesn't seem like the right way to do it. We also need to think about how to transition away from the Deprecated classfile attribute (JVMS 4.7.15). When compiling, providing the annotation also writes the classfile attribute, but providing the javadoc tag only writes the classfile attribute. When reading a class file, javac honors both. Maybe one step would be to have the javadoc tag synthesize an annotation if it isn't present. In fact, I think this would be a good idea, as it simplifies deprecation tools (such as the ones I'm writing) so that they don't have to worry about checking for the classfile attribute. I suppose in the fullness of time it might be reasonable to deprecate the Deprecated classfile attribute (!) but I'm not sure it's worth it.
11-08-2016
I see that there is already a "dep-ann" lint category that warns when an entity is tagged with a javac @deprecated comment, but not with a @Deprecated annotation. using this diagnostic property: compiler.warn.missing.deprecated.annotation=\ deprecated item is not annotated with @Deprecated So the present task is make this warning appear even without -Xlint:dep-ann for source 9. Secondly to make the @deprecated comment without @Deprecated annotation a nop for -source 9
09-08-2016
@Jon, correct; IMO under -source 9 (and above) javac should unconditionally denigrate a @deprecated javadoc tag that is not paired with a @Deprecated annotation.
10-02-2015
From which I infer that you are recommending that this is an unconditional warning, and is not related to any lint setting, right?
06-02-2015
Concretely, I'm recommending for -source 9, if the @deprecated javadoc appears on an element and the element is *not* also @Deprecated, javac issues a warning "You are missing @Deprecated" and does *not* treat the element as effectively deprecated. Phrased, differently, for source 9 the only elements treated as deprecated as those which are @Deprecated.
05-02-2015
Re: warning messages: are you suggesting a lint warning or an "unconditional" warning, that can only be removed by fixing the issue in the source -- that would make it analogous to warnings like the one for "ambiguous null for a varargs parameter"
05-02-2015