I haven't verified this through any test (actually I'm wondering how to
deterministically reproduce it), but logically there are cases where
gc.collect() (and, similarly, PyGC_Collect()) won't work as advertised.

Specifically, when the GC is asked to collect a given generation but a
younger generation is already being collected, collect() will simply
notice this and return 0. However, only the younger generation will have
been collected, not the generation asked by the user.

It wouldn't take too much effort to make gc.collect() and PyGC_Collect()
truely deterministic.

It should be possible to trigger this by invoking gc.collect in an
__del__ implementation of an object that is attached to a cycle.

However, I don't think this is an important issue; +0 for resolving this
by documenting the status quo (instead of making the implementation
match the documentation).