GeezerVison

@bsolomon1124 Thanks for the PR. I think it's certainly worthwhile to document the macro, especially considering how common it's utilized.

But, I'm in agreement with the changes recommended by @ammaraskar: removing the description of the internals and adding a brief example.

All the suggested changes here make sense and I'll add them when I have a chance.

I also think it might be worth mentioning the stated use of these macros:

Use the PyDoc_STR() or PyDoc_STRVAR() macro for docstrings to support building Python without docstrings (./configure --without-doc-strings).

https://www.python.org/dev/peps/pep-0007/#documentation-strings

Do you think that is also extraneous detail @aeros167 @ammaraskar ?

I think that might be worth adding, but I would recommend linking to the PEP itself using an inline Sphinx role:

Use the ``PyDoc_STR()`` or ``PyDoc_STRVAR()`` macro for docstrings to support
building Python without docstrings, as specified in :pep:`7`.

This provides readers a location for further information and means that we don't have to update this section if the syntax ever changes for ./configure --without-doc-string.

But, if it is decided that the exact syntax should be specified in the docs, inline codeblocks should be used instead of parentheses. This also applies to the macros, optionally Sphinx roles can be used for those (they're not needed if the definition for the macro is immediately nearby or within its own definition, as the link would be fairly pointless).

@ammaraskar I've added a section for PyDoc_STR also here. Appreciate if you have time for another review.

While I think it's probably okay in this case, I'd generally recommend against including additional sections in a PR that are outside of the scope of the original issue that it's attached to. The scope of this issue was specifically adding documentation for PyDoc_STRVAR.

Going outside of the scope can substantially to the required review time, particularly if you already have received several reviews on the PR. It may not seem like much in this case, but it can really add up when you consider the total volume of open PRs and our limited review time (it's mostly volunteer-driven).

An exception to the above is if you specifically ask a core developer about it and they approve of including additional related changes in the PR. There's also the option of simply opening a second PR and attaching it to the same issue; assuming they're both related.

Thanks @bsolomon1124 for the PR, and @zware for merging it 🌮🎉.. I'm working now to backport this PR to: 3.7.
🐍🍒⛏🤖

Thanks @bsolomon1124 for the PR, and @zware for merging it 🌮🎉.. I'm working now to backport this PR to: 3.8.
🐍🍒⛏🤖

Sorry, @bsolomon1124 and @zware, I could not cleanly backport this to 3.7 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker b54e46cb57ebac5c525a9a6be241412cd57bc935 3.7

Sorry @bsolomon1124 and @zware, I had trouble checking out the 3.8 backport branch.
Please backport using cherry_picker on command line.
cherry_picker b54e46cb57ebac5c525a9a6be241412cd57bc935 3.8

GH-19727 is a backport of this pull request to the 3.8 branch.

GH-19728 is a backport of this pull request to the 3.7 branch.