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

[Aleksey Shipilev]

On Fri, 22 Aug 2025 22:54:07 GMT, Rui Li <duke at openjdk.org> wrote:

>> Add documentation of Shenandoah to java man page
>> 
>> Aside from `-XX:+UseShenandoahGC`, I picked flags from [shenandoah_globals.hpp](https://github.com/openjdk/jdk/blob/master/src/hotspot/share/gc/shenandoah/shenandoah_globals.hpp) that are at product level but not experimental / diagnostic to avoid overwhelming info. Two additional flags match: `ShenandoahGCMode` and `ShenandoahGCHeuristics`
>
> Rui Li has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Comment for aggressive. Indent.

src/java.base/share/man/java.md line 2899:

> 2897: 
> 2898:     `satb`
> 2899:     :   Snapshot-at-the-beginning concurrent GC (three pass mark-evac-update).

This is a long-standing problem with the name. It kinda implies `generational` is not `satb`. It actually is. Maybe we should rename `satb` to `single` or something. A lot of bikeshedding would ensue.

src/java.base/share/man/java.md line 2903:

> 2901:     `passive`
> 2902:     :   Stop the world GC only (either degenerated or full). This mode is
> 2903:         diagnostic, and must be enabled via `-XX:+UnlockDiagnosticVMOptions`.

I don't think we add diagnostic options to the generic options list. These are not for end users, and we do not surface them unnecessarily.

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.

src/java.base/share/man/java.md line 2923:

> 2921:     `aggressive`
> 2922:     :   Run GC continuously, try to evacuate everything. This heuristics is
> 2923:         diagnostic, and must be enabled via -XX:+UnlockDiagnosticVMOptions.

Same here: diagnostic option.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/26907#discussion_r2297835685
PR Review Comment: https://git.openjdk.org/jdk/pull/26907#discussion_r2297834019
PR Review Comment: https://git.openjdk.org/jdk/pull/26907#discussion_r2297837196
PR Review Comment: https://git.openjdk.org/jdk/pull/26907#discussion_r2297835963