Summary

Programs that apply the @deprecated javadoc tag to record components are being rejected by javac. These programs are being rejected regardless of the application or not of the @Deprecated annotation to the corresponding record component. The presence of the @deprecated javadoc tag shouldn't trigger any special action by the javac compiler.

Problem

Javac is rejecting programs that apply the @deprecated javadoc tag to record components. Regardless of the application or not of the @Deprecated annotation to the corresponding record component. This contradicts the specification for the @deprecated javadoc tag and the @Deprecated annotation, both of which recommend joint use.

Solution

Javac should not issue an error when the @deprecated javadoc tag if applied to a record component.

Specification

From the JavaDoc Documentation Comment Specification for the Standard Doclet (JDK 25) [1] we have the following specification for the @deprecated javadoc tag:

    deprecated

        @deprecated deprecated-text

    This tag is used in conjunction with the @Deprecated annotation to indicate that this API should no longer be used (even though it may continue to work). The standard doclet moves deprecated text ahead of the main description, placing it in italics and preceding it with a bold warning.

    The first sentence of deprecated text should tell the user when the API was deprecated and what to use as a replacement. The standard doclet copies the first sentence to the summary section and index. Subsequent sentences can also explain why it was deprecated. You should include a link tag that points to the replacement API.

    Note:

        For historical reasons, when used in a traditional documentation comment, the use of the deprecated tag is enough by itself to mark the associated declaration as deprecated, even if the @Deprecated annotation is not used.
        In Markdown documentation comments, the @Deprecated annotation must be used to mark the declaration as deprecated; the deprecated tag is just an adjunct to provide descriptive details.
        The tag will be ignored if the annotation is not also present.

    Introduced in JDK 1.0.

This specification suggests that the @Deprecated annotation should be used whenever the @deprecated javadoc tag is used and vice-versa. As it is also suggested by the specification for java.lang.Deprecated:

    @apiNote
    It is strongly recommended that the reason for deprecating a program element
    be explained in the documentation, using the {@code @deprecated}
    javadoc tag. The documentation should also suggest and link to a
    recommended replacement API, if applicable. A replacement API often
    has subtly different semantics, so such issues should be discussed as
    well.
    
    <p>It is recommended that a {@code since} value be provided with all newly
    annotated program elements. Note that {@code since} cannot be mandatory,
    as there are many existing annotations that lack this element value.
    
    <p>There is no defined order among annotation elements. As a matter of
    style, the {@code since} element should be placed first.
    
    <p>The {@code @Deprecated} annotation should always be present if
    the {@code @deprecated} javadoc tag is present, and vice-versa.

the other related piece of specification related here is the table at [2] that specifies where javadoc tags can be used, reproducing only the row related to the @deprecated tag below:

Notes:

    Methods includes members of annotation interfaces.
    Fields includes members of enum classes.
    Other includes the Overview page, which is not tied to any declaration,
    and HTML and Markdown files in doc-files subdirectories of a module or package directory. 
    The Overview page is typically specified with an option to the javadoc command.

This implies that the @deprecated tag can't be used on record components.

[1] https://docs.oracle.com/en/java/javase/25/docs/specs/javadoc/doc-comment-spec.html [2] https://docs.oracle.com/en/java/javase/25/docs/specs/javadoc/doc-comment-spec.html#where-tags-can-be-used