Skip to content

Make it clear Py_VISIT is a macro in the docs#133688

Merged
kumaraditya303 merged 2 commits into
python:mainfrom
da-woods:visit-docs
May 18, 2025
Merged

Make it clear Py_VISIT is a macro in the docs#133688
kumaraditya303 merged 2 commits into
python:mainfrom
da-woods:visit-docs

Conversation

@da-woods

@da-woods da-woods commented May 8, 2025 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Contributor

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/

@da-woods
Make it clear Py_VISIT is a macro in the docs
1b96cc1 
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.
@bedevere-app bedevere-app Bot added docs Documentation in the Doc dir skip news awaiting review labels May 8, 2025
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs May 8, 2025
ZeroIntensity
ZeroIntensity reviewed May 9, 2025
View reviewed changes
Comment thread Doc/c-api/gcsupport.rst Outdated
ZeroIntensity
ZeroIntensity reviewed May 11, 2025
View reviewed changes

@ZeroIntensity ZeroIntensity left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

ZeroIntensity commented May 11, 2025

Copy link
Copy Markdown
Member

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

@da-woods

da-woods commented May 11, 2025

Copy link
Copy Markdown
Contributor Author

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
ZeroIntensity approved these changes May 11, 2025
View reviewed changes

@ZeroIntensity ZeroIntensity left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@ZeroIntensity ZeroIntensity added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels May 11, 2025
@ZeroIntensity ZeroIntensity requested a review from encukou May 11, 2025 16:53
@kumaraditya303 kumaraditya303 merged commit bb32f3c into python:main May 18, 2025
36 checks passed
@miss-islington-app

miss-islington-app Bot commented May 18, 2025

Copy link
Copy Markdown

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

@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs May 18, 2025
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request May 18, 2025
@da-woods @miss-islington
document Py_VISIT as a macro in the docs (pythonGH-133688)
657910c 
(cherry picked from commit bb32f3c)

Co-authored-by: da-woods <dw-git@d-woods.co.uk>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request May 18, 2025
@da-woods @miss-islington
document Py_VISIT as a macro in the docs (pythonGH-133688)
55a0271 
(cherry picked from commit bb32f3c)

Co-authored-by: da-woods <dw-git@d-woods.co.uk>
@bedevere-app

bedevere-app Bot commented May 18, 2025

Copy link
Copy Markdown

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

@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label May 18, 2025
@bedevere-app

bedevere-app Bot commented May 18, 2025

Copy link
Copy Markdown

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

@bedevere-app bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label May 18, 2025
@da-woods da-woods deleted the visit-docs branch May 18, 2025 16:29
kumaraditya303 pushed a commit that referenced this pull request May 18, 2025
@miss-islington @da-woods
[3.14] document Py_VISIT as a macro in the docs (GH-133688) (#134186)
76957eb 
document `Py_VISIT` as a macro in the docs (GH-133688)
(cherry picked from commit bb32f3c)

Co-authored-by: da-woods <dw-git@d-woods.co.uk>
kumaraditya303 pushed a commit that referenced this pull request May 18, 2025
@miss-islington @da-woods
[3.13] document Py_VISIT as a macro in the docs (GH-133688) (#134187)
018ec63 
document `Py_VISIT` as a macro in the docs (GH-133688)
(cherry picked from commit bb32f3c)

Co-authored-by: da-woods <dw-git@d-woods.co.uk>
Pranjal095 pushed a commit to Pranjal095/cpython that referenced this pull request Jul 12, 2025
@da-woods @Pranjal095
document Py_VISIT as a macro in the docs (python#133688)
c259788
taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025
@da-woods @taegyunkim
document Py_VISIT as a macro in the docs (python#133688)
e2b57be
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ZeroIntensity ZeroIntensity ZeroIntensity approved these changes

@kumaraditya303 kumaraditya303 kumaraditya303 approved these changes

@encukou encukou Awaiting requested review from encukou

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip issue skip news topic-C-API

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@da-woods @ZeroIntensity @kumaraditya303