From b54e46cb57ebac5c525a9a6be241412cd57bc935 Mon Sep 17 00:00:00 2001
From: Brad Solomon <brad.solomon.1124@gmail.com>
Date: Sun, 26 Apr 2020 22:31:44 -0400
Subject: [PATCH] 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.
---
 Doc/c-api/intro.rst                           | 33 +++++++++++++++++++
 Doc/c-api/module.rst                          |  2 +-
 .../2019-10-06-23-44-15.bpo-38387.fZoq0S.rst  |  1 +
 3 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst

diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 5a99631bbbd..e89a788de0d 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -187,6 +187,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 cf1df280736..8a415dfa30a 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 00000000000..a678fe50526
--- /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.