8000 bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros (GH-16… · python/cpython@b54e46c · GitHub
[go: up one dir, main page]

Skip to content

Commit b54e46c

Browse files
authored
bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros (GH-16607)
Adds a short description of `PyDoc_STRVAR` and `PyDoc_STR` to "Useful macros" section of C-API docs. Currently, there is [one lone mention](https://docs.python.org/3/c-api/module.html?highlight=pydoc_strvar#c.PyModuleDef) in the C-API reference, despite the fact that `PyDoc_STRVAR` is ubiquitous to `Modules/`. Additionally, this properly uses `c:macro` within `Doc/c-api/module.rst` to link.
1 parent a494caa commit b54e46c

File tree

3 files changed

+35
-1
lines changed

3 files changed

+35
-1
lines changed

Doc/c-api/intro.rst

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,39 @@ complete listing.
187187
.. versionchanged:: 3.8
188188
MSVC support was added.
189189

190+
.. c:macro:: PyDoc_STRVAR(name, str)
191+
192+
Creates a variable with name ``name`` that can be used in docstrings.
193+
If Python is built without docstrings, the value will be empty.
194+
195+
Use :c:macro:`PyDoc_STRVAR` for docstrings to support building
196+
Python without docstrings, as specified in :pep:`7`.
197+
198+
Example::
199+
200+
PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");
201+
202+
static PyMethodDef deque_methods[] = {
203+
// ...
204+
{"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
205+
// ...
206+
}
207+
208+
.. c:macro:: PyDoc_STR(str)
209+
210+
Creates a docstring for the given input string or an empty string
211+
if docstrings are disabled.
212+
213+
Use :c:macro:`PyDoc_STR` in specifying docstrings to support
214+
building Python without docstrings, as specified in :pep:`7`.
215+
216+
Example::
217+
218+
static PyMethodDef pysqlite_row_methods[] = {
219+
{"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
220+
PyDoc_STR("Returns the keys of the row.")},
221+
{NULL, NULL}
222+
};
190223

191224
.. _api-objects:
192225

Doc/c-api/module.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,7 +153,7 @@ or request "multi-phase initialization" by returning the definition struct itsel
153153
.. c:member:: const char *m_doc
154154
155155
Docstring for the module; usually a docstring variable created with
156-
:c:func:`PyDoc_STRVAR` is used.
156+
:c:macro:`PyDoc_STRVAR` is used.
157157
158158
.. c:member:: Py_ssize_t m_size
159159
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Document :c:macro:`PyDoc_STRVAR` macro in the C-API reference.

0 commit comments

Comments
 (0)
0