Documentation of Java options and --patch-module

[Volker Simonis]

Hi,

recently a customer ran into some issues which we couldn't easily
understand. It turned out he had used the --patch-module option to
replace some of the JDK core library classes with versions customized
by him. I told him that --patch-module is a development flag not
supported in production but he didn't believe me and pointed me to to
the official "Overview of Java Options" [1] which indeed lists
--patch-module as an "Extra Option" (i.e. "General purpose options
that are specific to the Java HotSpot Virtual Machine") along other
common, production-grade options like e.g. -Xlog, -Xms, -Xshare.

JEP 261 (Module System) on the other side described the --patch-modle
option with the following bold disclaimer [2]:

"The --patch-module option is intended only for testing and debugging.
Its use in production settings is strongly discouraged."

I think this is especially true when applying --patch-module to Java
platform modules like java.base.

I'd like to propose that we add this disclaimer to the "Overview of
Java Options" [1] as well as to the output of "java --help" (which has
similar information) to set the right expectations on the user side
and prevent disappointment when these options don't produce the
expected results. We could e.g. add a new section with "Testing and
Debugging Options" which make it clear that the corresponding options
are not intended and supported for productive usage.

What do you think?

Best regards,
Volker

[1] https://docs.oracle.com/en/java/javase/18/docs/specs/man/java.html
[2] https://openjdk.org/jeps/261