RFR: 8246037: Shenandoah: update man pages to mention -XX:+UseShenandoahGC [v2]

[Y. Srinivas Ramakrishna]

On Mon, 25 Aug 2025 23:22:16 GMT, Rui Li <duke at openjdk.org> wrote:

>> src/java.base/share/man/java.md line 2919:
>> 
>>> 2917: 
>>> 2918:     `static`
>>> 2919:     :   Trigger GC when free heap falls below the ShenandoahMinFreeThreshold.
>> 
>> Same here: `ShenandoahMinFreeThreshold` is experimental, it is not worth mentioning here. In fact, there are tunables for `adaptive` and `compact` as well, yet we do not (correctly!) mention them.
>
> True, other options respond to `ShenandoahMinFreeThreshold` as well. It's kinda hard to describe `static` option without mentioning the threshold. 
> - We could make the doc vague as in the [shenandoah_globals.hpp](https://github.com/openjdk/jdk/blob/master/src/hotspot/share/gc/shenandoah/shenandoah_globals.hpp#L147): `trigger GC when free heap falls below the threshold`. 
> - I now wonder why `static` is a non experimental flag - it has to be used with other experimental flags. Maybe just drop static from man page as well?

`below a specified threshold` might sound appropriately vague and render the flag unusable unless one consulted the code, underlining the experimental nature of it.

If the collector respects `static` as specified, it can be considered a good guardrail to use in anger. In fact, I know of teams that do in production. (For that matter, there are a couple who use `compact` as well.)

However, I am fine with eliding all experimental options, and in turn any non-experimental options that depend on experimental options (which however seems to be an anti-pattern to be avoided, if possible).

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/26907#discussion_r2299472120