[Python-checkins] [3.8] bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros (GH-16607) (GH-19727)
Zachary Ware
webhook-mailer at python.org
Sun Apr 26 22:45:14 EDT 2020
https://github.com/python/cpython/commit/ca5649c4c1ab260c8ceb8a57ec703c06e2707986
commit: ca5649c4c1ab260c8ceb8a57ec703c06e2707986
branch: 3.8
author: Zachary Ware <zach at python.org>
committer: GitHub <noreply at github.com>
date: 2020-04-26T21:45:05-05:00
summary:
[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 at gmail.com>
files:
A Misc/NEWS.d/next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst
M Doc/c-api/intro.rst
M Doc/c-api/module.rst
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index d08d4f97a308e..718f40eb6c247 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 57902a9c7f838..d2b8f4c12503e 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 0000000000000..a678fe5052673
--- /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.
More information about the Python-checkins
mailing list