8000 [3.7] bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros … · python/cpython@70ba814 · GitHub
[go: up one dir, main page]

Skip to content

Commit 70ba814

Browse files
zwarebsolomon1124
andauthored
[3.7] bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros (GH-16607) (GH-19728)
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_strvarGH-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.. (cherry picked from commit b54e46c) Co-authored-by: Brad Solomon <brad.solomon.1124@gmail.com>
1 parent fd32a0e commit 70ba814

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
@@ -162,6 +162,39 @@ complete listing.
162162

163163
.. versionadded:: 3.4
164164

165+
.. c:macro:: PyDoc_STRVAR(name, str)
166+
167+
Creates a variable with name ``name`` that can be used in docstrings.
168+
If Python is built without docstrings, the value will be empty.
169+
170+
Use :c:macro:`PyDoc_STRVAR` for docstrings to support building
171+
Python without docstrings, as specified in :pep:`7`.
172+
173+
Example::
174+
175+
PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element.");
176+
177+
static PyMethodDef deque_methods[] = {
178+
// ...
179+
{"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc},
180+
// ...
181+
}
182+
183+
.. c:macro:: PyDoc_STR(str)
184+
185+
Creates a docstring for the given input string or an empty string
186+
if docstrings are disabled.
187+
188+
Use :c:macro:`PyDoc_STR` in specifying docstrings to support
189+
building Python without docstrings, as specified in :pep:`7`.
190+
191+
Example::
192+
193+
static PyMethodDef pysqlite_row_methods[] = {
194+
{"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS,
195+
PyDoc_STR("Returns the keys of the row.")},
196+
{NULL, NULL}
197+
};
165198

166199
.. _api-objects:
167200

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