gc.collect() docs are wrong

[JelleZijlstra]

https://docs.python.org/3/library/gc.html#gc.collect says "The number of unreachable objects found is returned."

In fact, it returns (

cpython/Modules/gcmodule.c

Line 1378 in 48dfd74

return n + m;

) the sum of two numbers: the number of objects collected plus the number of uncollectable objects. The docs should be changed.

(What makes an object uncollectable? I didn't read too closely but it seems to have something to do with finalizers.)

Linked PRs

• gh-112502: Docs: Improve docs for gc.collect method #112562

[sekomer]

I checked the gcmodule.c and you are right, I created a pr for this issue.

[olutra]

To be fair, "The sum of collected objects and uncollectable objects" is exactly "The number of unreachable objects found", so docs weren't wrong. It was confusing, because there is no definition of the unreachable objects on the page, but new wording isn't necessarily less confusing. Two numbers are summed and returned as one, and it becomes impossible to deduce each number from the sum. To me it seems to be an internal implementation detail that should not be propagated to higher levels.

I think a better way would be to put a definition of unreachable objects somewhere on the page, because unreachable is also used in a couple of other places on the page.
Previous wording "The number of unreachable objects found is returned." didn't indicate that objects weren't only found but also processed. Current wording indicates that collectable objects were collected, but doesn't say that uncollectable objects are also processed (moved to garbage) and won't be included in the next collection.

[pablogsal]

@olutra would you like to create a PR with your suggestions?