diff options
| author | Zachary Ware <zach@python.org> | 2020-04-27 02:45:05 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2020-04-27 02:45:05 (GMT) |
| commit | ca5649c4c1ab260c8ceb8a57ec703c06e2707986 (patch) | |
| tree | 03a8a707323c338f72f214a81d1337e80b387495 | |
| parent | 179f22c3b786ce9baa3445923f8f9708dfa5d5b7 (diff) | |
| download | cpython-ca5649c4c1ab260c8ceb8a57ec703c06e2707986.zip cpython-ca5649c4c1ab260c8ceb8a57ec703c06e2707986.tar.gz cpython-ca5649c4c1ab260c8ceb8a57ec703c06e2707986.tar.bz2 | |
[3.8] bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros (GH-16607) (GH-19727)
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)
Authored-by: Brad Solomon <brad.solomon.1124@gmail.com>
| -rw-r--r-- | Doc/c-api/intro.rst | 33 | ||||
| -rw-r--r-- | Doc/c-api/module.rst | 2 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst | 1 |
3 files changed, 35 insertions, 1 deletions
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index d08d4f9..718f40e 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -174,6 +174,39 @@ complete listing. .. versionchanged:: 3.8 MSVC support was added. +.. c:macro:: PyDoc_STRVAR(name, str) + + Creates a variable with name ``name`` that can be used in docstrings. + If Python is built without docstrings, the value will be empty. + + Use :c:macro:`PyDoc_STRVAR` for docstrings to support building + Python without docstrings, as specified in :pep:`7`. + + Example:: + + PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element."); + + static PyMethodDef deque_methods[] = { + // ... + {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc}, + // ... + } + +.. c:macro:: PyDoc_STR(str) + + Creates a docstring for the given input string or an empty string + if docstrings are disabled. + + Use :c:macro:`PyDoc_STR` in specifying docstrings to support + building Python without docstrings, as specified in :pep:`7`. + + Example:: + + static PyMethodDef pysqlite_row_methods[] = { + {"keys", (PyCFunction)pysqlite_row_keys, METH_NOARGS, + PyDoc_STR("Returns the keys of the row.")}, + {NULL, NULL} + }; .. _api-objects: diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index 57902a9..d2b8f4c 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -153,7 +153,7 @@ or request "multi-phase initialization" by returning the definition struct itsel .. c:member:: const char *m_doc Docstring for the module; usually a docstring variable created with - :c:func:`PyDoc_STRVAR` is used. + :c:macro:`PyDoc_STRVAR` is used. .. c:member:: Py_ssize_t m_size diff --git a/Misc/NEWS.d/next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst b/Misc/NEWS.d/next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst new file mode 100644 index 0000000..a678fe5 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst @@ -0,0 +1 @@ +Document :c:macro:`PyDoc_STRVAR` macro in the C-API reference. |