JRMP static stubs have already been deprecated. This is mainly advertised through documentation, and also by warning messages when rmic is run. However, the actual generated static stubs don't have a @Deprecated annotation. This is not a big deal at present, deprecation warnings would only be issued at compile time, and generally applications do not compile against stub classes. (Instead, they compile against the remote interface.) However, the @Deprecation annotation has runtime retention, and in the future there may be runtime checking of deprecated classes and class members. Having RMI static stubs participate in such checking would be useful.

This would argue for making JRMP static stubs (note, not CORBA/IIOP static stubs) deprecated by default. In general however RMI static stubs will continue to be supported for some time. Certain consumers of RMI may wish to retire static stubs for their protocol well before RMI itself removes static stub support. Thus they may wish to tag and document their stubs differently from the default. This would argue for options to rmic to control this and perhaps to let caller specify documentation to be supposed with the javadoc @deprecated tag.

Regarding documentation, it's not clear whether the actual generated stub source code is used for generating the javadoc. In some cases there is no javadoc at all for generated stub classes even though they are a public part of the Java SE API. In other cases (ActivationGroup_Stub.java) the generated stub class has been modified -- and actually stubbed out! -- and documentation has been added to it; and this documentation stub has been checked into the source repo and is used only for javadoc generation but not for compiling into the class library.

In the JDK, each consumer of RMI that has static stubs in the Java SE public API (e.g., JMX, jstatd, possibly others) probably deals with this somewhat differently and thus the issues will have to be addressed differently.

Meanwhile, it would be nice to enhance rmic to add the @deprecated javadoc tag, and possibly other javadoc (perhaps just the full class doc?) to remove the need to have a separate documentation stub.