From b68431cc1f4946dfdebf89f77c649f9a425ff8c0 Mon Sep 17 00:00:00 2001 From: Brad Solomon Date: Sun, 6 Oct 2019 19:35:11 -0400 Subject: [PATCH 1/5] Formally document PyDoc_STRVAR macro --- Doc/c-api/intro.rst | 11 +++++++++++ Doc/c-api/module.rst | 2 +- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index d08d4f97a308e7..16d890287bece1 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -174,6 +174,17 @@ complete listing. .. versionchanged:: 3.8 MSVC support was added. +.. c:macro:: PyDoc_STRVAR(name, str) + + A shortcut for ``static const char name[] = str``, commonly used + to initialize a module, function, class, or method docstring. + + Example:: + + PyDoc_STRVAR(module_doc, "This is the module's docstring."); + + .. versionchanged:: 3.8 + This macro previously inserted ``static char name[]``. .. _api-objects: diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index 57902a9c7f8384..d2b8f4c12503e7 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 From 7d951038e85867892c23a661e57a9c5aa0ce97ad Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" <43283697+blurb-it[bot]@users.noreply.github.com> Date: Sun, 6 Oct 2019 23:44:17 +0000 Subject: [PATCH 2/5] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?= =?UTF-8?q?rb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst 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 00000000000000..d769f327756703 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst @@ -0,0 +1 @@ +Document PyDoc_STRVAR macro in the C-API reference. \ No newline at end of file From 097553f30781e659c0d197beda5b090c778e8289 Mon Sep 17 00:00:00 2001 From: Brad Solomon Date: Mon, 7 Oct 2019 10:03:48 -0400 Subject: [PATCH 3/5] Modify PyDoc_STRVAR example; mention PEP 7 --- Doc/c-api/intro.rst | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 16d890287bece1..ccc4ae61d8fdb8 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -176,15 +176,21 @@ complete listing. .. c:macro:: PyDoc_STRVAR(name, str) - A shortcut for ``static const char name[] = str``, commonly used - to initialize a module, function, class, or method docstring. + Creates a variable with name ``name`` that can be used in docstrings. + + Use the :c:macro:`PyDoc_STRVAR` or :c:macro:`PyDoc_STR` macros for + docstrings to support building Python without docstrings, + as specified in :pep:`7`. Example:: - PyDoc_STRVAR(module_doc, "This is the module's docstring."); + PyDoc_STRVAR(pop_doc, "Remove and return the rightmost element."); - .. versionchanged:: 3.8 - This macro previously inserted ``static char name[]``. + static PyMethodDef deque_methods[] = { + // ... + {"pop", (PyCFunction)deque_pop, METH_NOARGS, pop_doc}, + // ... + } .. _api-objects: From 644b8ae0cb1dfadabd48c5721316b7c93f2175e6 Mon Sep 17 00:00:00 2001 From: Brad Solomon Date: Mon, 7 Oct 2019 10:19:07 -0400 Subject: [PATCH 4/5] Use proper RST in news entry --- .../next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index d769f327756703..a678fe5052673b 100644 --- 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 @@ -1 +1 @@ -Document PyDoc_STRVAR macro in the C-API reference. \ No newline at end of file +Document :c:macro:`PyDoc_STRVAR` macro in the C-API reference. From c05b5bac74d625b6dfb6367b8f0985c9ebf263d1 Mon Sep 17 00:00:00 2001 From: Brad Solomon Date: Sun, 26 Jan 2020 18:29:46 -0500 Subject: [PATCH 5/5] Document PyDoc_STR alongside PyDoc_STRVAR --- Doc/c-api/intro.rst | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index ccc4ae61d8fdb8..718f40eb6c2474 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -177,10 +177,10 @@ complete listing. .. 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 the :c:macro:`PyDoc_STRVAR` or :c:macro:`PyDoc_STR` macros for - docstrings to support building Python without docstrings, - as specified in :pep:`7`. + Use :c:macro:`PyDoc_STRVAR` for docstrings to support building + Python without docstrings, as specified in :pep:`7`. Example:: @@ -192,6 +192,22 @@ complete listing. // ... } +.. 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: Objects, Types and Reference Counts