This does not compile:

public record Test(
    /**
     * @deprecated
     */
    int i
) {}

The error is:

> error: record components cannot have modifiers

I don't see this being documented:

- In the JLS: https://docs.oracle.com/javase/specs/jls/se25/html/jls-8.html#jls-8.10.1
- In the Javadoc documentation: https://docs.oracle.com/en/java/javase/25/docs/specs/javadoc/doc-comment-spec.html#deprecated
- The Deprecated annotation documentation: https://docs.oracle.com/en/java/javase/25/docs/api//java.base/java/lang/Deprecated.html

The latter specifically claims that "The @Deprecated annotation should always be present if the @deprecated javadoc tag is present, and vice-versa."

This contract on @Deprecated seems to hint at the error being a wrong error reported by javac in the first place. That, as well as the fact that javac shouldn't concern itself with Javadoc syntax to this extent.

If the error is justified, I think it needs to be better documented, both in the error message, and the various locations mentioned above.

The workaround is to use only the @Deprecated annotation:

public record Test(
    /**
     * ...
     */
    @Deprecated
    int i
) {}