A DESCRIPTION OF THE PROBLEM :
The documentation for System.gc() is extremely misleading and fails to make reference to the recommended practise of _never_ calling System.gc().

The choice of language leaves it unclear what the behaviour would be when System.gc() is called and what external factors will influence the behaviour.


EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Calling the gc method asks the Java Virtual Machine to expend effort toward recycling unused objects in order to make the memory they currently occupy available for quick reuse. When control returns from the method call, the Java Virtual Machine may have made a best effort to reclaim space from all discarded objects.

The documentation should state that use of this method is not recommended and should provide a reference to the GC FAQ http://java.sun.com/docs/hotspot/gc1.4.2/faq.html and the GC tuning guide http://java.sun.com/docs/hotspot/gc5.0/gc_tuning_5.html

The documentation should make reference to the fact that it's possible to prevent the gc() method from doing anything by using certain jvm configurations.
ACTUAL -
Calling the gc method suggests that the Java Virtual Machine expend effort toward recycling unused objects in order to make the memory they currently occupy available for quick reuse. When control returns from the method call, the Java Virtual Machine has made a best effort to reclaim space from all discarded objects.

URL OF FAULTY DOCUMENTATION :
http://java.sun.com/javase/6/docs/api/java/lang/System.html#gc()