A DESCRIPTION OF THE PROBLEM :
The useful JVM flag -XX:-UseGCTimeLimit is only documented in bug reports like:

  http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5024647
  http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4976274
  http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6190472
  http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6185487

It should be mentioned on the GC ergonomics page.

If there is an analogous JVM flag for waiving the "space-limit" to be freed on a major GC -- something like "-XX:-UseGCHeapFreeLimit"-- it should be documented, too.

The method for determining the "time spent in GC" -- specifically how the sampling interval is chosen -- should be documented somewhere, also. I think my application may be getting spurious OutOfMemoryErrors because of periods where GC dominates for 'too long', though it's not 'too long' overall. The docs do not make it clear how much previous clock time is considered before making the 'too long' determination... 30 seconds? 15 minutes? since launch?


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
mention of the -XX:-UseGCTimeLimit flag, details on the time-limit sampling interval
ACTUAL -
mention of the time-limit, with no info about how to turn it off or how the sampling interval is chosen

URL OF FAULTY DOCUMENTATION :
http://java.sun.com/j2se/1.5.0/docs/guide/vm/gc-ergonomics.html
###@###.### 2005-06-20 06:46:28 GMT