8000 [3.7] bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros (GH-16607) by zware · Pull Request #19728 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

[3.7] bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros (GH-16607) #19728

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 27, 2020
Merged

[3.7] bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros (GH-16607) #19728

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
[3.7] bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros (G… 
…H-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_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>
  • Loading branch information
@bsolomon1124 @zware
bsolomon1124 authored and zware committed Apr 27, 2020
commit d3244ac510e9e0f14443fbcb79a75f8083eb2e9c
33 changes: 33 additions & 0 deletions Doc/c-api/intro.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,39 @@ complete listing.

.. versionadded:: 3.4

.. 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:

Expand Down
2 changes: 1 addition & 1 deletion Doc/c-api/module.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions Misc/NEWS.d/next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document :c:macro:`PyDoc_STRVAR` macro in the C-API reference.
0