Make it clear Py_VISIT is a macro in the docs

[da-woods]

It has the hidden return inside it, so to me the void return type is a little misleading because it implies that it behaves like a C function.

---

📚 Documentation preview 📚: https://cpython-previews--133688.org.readthedocs.build/

[ZeroIntensity]

There are a few other places where a function is documented instead of a macro, e.g. any of the reference count APIs. I'm not opposed to changing everything, but what's the benefit here?

[ZeroIntensity]

Oh wait, bad example--the reference count APIs are static inline functions, not macros. Oops. Pretend I said Py_CLEAR.

[da-woods]

There are a few other places where a function is documented instead of a macro, e.g. any of the reference count APIs. I'm not opposed to changing everything, but what's the benefit here?

My opinion is that most of the reference counting API could be substituted for a function (and in some cases, has been). The ones that really couldn't be replaced by a function like Py_SETREF are documented as macros.

Py_VISIT couldn't be implemented as a function because it has a return in it, and that's what I found confusing about the way it's currently documented.

Oh wait, bad example--the reference count APIs are static inline functions, not macros. Oops. Pretend I said Py_CLEAR.

My opinion would be that Py_CLEAR might be better documented as a macro.

---

I don't feel hugely strongly about this - I'm not going to argue if you don't think it's an improvement. But that's the reasoning for why I proposed the change.

[ZeroIntensity]

Ok, yeah, let's go with this. Py_VISIT can return the caller, which isn't at all clear when it's documented as a function. Let's also fix Py_CLEAR in a follow-up.

[miss-islington-app]

Thanks @da-woods for the PR, and @kumaraditya303 for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[bedevere-app]

GH-134186 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-134187 is a backport of this pull request to the 3.13 branch.