Skip to content

Commit 312e16f

Browse files
arhadthedevmerwokJelleZijlstra
authored
[3.9] gh-91118: Fix docstrings that do not honor --without-doc-strings (GH-31769) (#91664)
Co-authored-by: Éric <merwok@netwok.org> Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> (cherry picked from commit a573cb2)
1 parent cb3c85d commit 312e16f

File tree

16 files changed

+77
-62
lines changed

16 files changed

+77
-62
lines changed

‎Doc/c-api/typeobj.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2482,7 +2482,7 @@ A basic static type::
24822482
PyVarObject_HEAD_INIT(NULL, 0)
24832483
.tp_name = "mymod.MyObject",
24842484
.tp_basicsize = sizeof(MyObject),
2485-
.tp_doc = "My objects",
2485+
.tp_doc = PyDoc_STR("My objects"),
24862486
.tp_new = myobj_new,
24872487
.tp_dealloc = (destructor)myobj_dealloc,
24882488
.tp_repr = (reprfunc)myobj_repr,
@@ -2512,7 +2512,7 @@ with a more verbose initializer::
25122512
0, /* tp_setattro */
25132513
0, /* tp_as_buffer */
25142514
0, /* tp_flags */
2515-
"My objects", /* tp_doc */
2515+
PyDoc_STR("My objects"), /* tp_doc */
25162516
0, /* tp_traverse */
25172517
0, /* tp_clear */
25182518
0, /* tp_richcompare */
@@ -2545,7 +2545,7 @@ A type that supports weakrefs, instance dicts, and hashing::
25452545
PyVarObject_HEAD_INIT(NULL, 0)
25462546
.tp_name = "mymod.MyObject",
25472547
.tp_basicsize = sizeof(MyObject),
2548-
.tp_doc = "My objects",
2548+
.tp_doc = PyDoc_STR("My objects"),
25492549
.tp_weaklistoffset = offsetof(MyObject, weakreflist),
25502550
.tp_dictoffset = offsetof(MyObject, inst_dict),
25512551
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
@@ -2572,7 +2572,7 @@ to create instances (e.g. uses a separate factory func)::
25722572
.tp_name = "mymod.MyStr",
25732573
.tp_basicsize = sizeof(MyStr),
25742574
.tp_base = NULL, // set to &PyUnicode_Type in module init
2575-
.tp_doc = "my custom str",
2575+
.tp_doc = PyDoc_STR("my custom str"),
25762576
.tp_flags = Py_TPFLAGS_DEFAULT,
25772577
.tp_new = NULL,
25782578
.tp_repr = (reprfunc)myobj_repr,

‎Doc/extending/newtypes_tutorial.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ The second bit is the definition of the type object. ::
8989
static PyTypeObject CustomType = {
9090
PyVarObject_HEAD_INIT(NULL, 0)
9191
.tp_name = "custom.Custom",
92-
.tp_doc = "Custom objects",
92+
.tp_doc = PyDoc_STR("Custom objects"),
9393
.tp_basicsize = sizeof(CustomObject),
9494
.tp_itemsize = 0,
9595
.tp_flags = Py_TPFLAGS_DEFAULT,
@@ -160,7 +160,7 @@ you will need to OR the corresponding flags.
160160

161161
We provide a doc string for the type in :c:member:`~PyTypeObject.tp_doc`. ::
162162

163-
.tp_doc = "Custom objects",
163+
.tp_doc = PyDoc_STR("Custom objects"),
164164

165165
To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new`
166166
handler. This is the equivalent of the Python method :meth:`__new__`, but

‎Doc/includes/custom.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ typedef struct {
99
static PyTypeObject CustomType = {
1010
PyVarObject_HEAD_INIT(NULL, 0)
1111
.tp_name = "custom.Custom",
12-
.tp_doc = "Custom objects",
12+
.tp_doc = PyDoc_STR("Custom objects"),
1313
.tp_basicsize = sizeof(CustomObject),
1414
.tp_itemsize = 0,
1515
.tp_flags = Py_TPFLAGS_DEFAULT,

‎Doc/includes/custom2.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ static PyMethodDef Custom_methods[] = {
9898
static PyTypeObject CustomType = {
9999
PyVarObject_HEAD_INIT(NULL, 0)
100100
.tp_name = "custom2.Custom",
101-
.tp_doc = "Custom objects",
101+
.tp_doc = PyDoc_STR("Custom objects"),
102102
.tp_basicsize = sizeof(CustomObject),
103103
.tp_itemsize = 0,
104104
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,

‎Doc/includes/custom3.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ static PyMethodDef Custom_methods[] = {
148148
static PyTypeObject CustomType = {
149149
PyVarObject_HEAD_INIT(NULL, 0)
150150
.tp_name = "custom3.Custom",
151-
.tp_doc = "Custom objects",
151+
.tp_doc = PyDoc_STR("Custom objects"),
152152
.tp_basicsize = sizeof(CustomObject),
153153
.tp_itemsize = 0,
154154
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,

‎Doc/includes/custom4.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ static PyMethodDef Custom_methods[] = {
160160
static PyTypeObject CustomType = {
161161
PyVarObject_HEAD_INIT(NULL, 0)
162162
.tp_name = "custom4.Custom",
163-
.tp_doc = "Custom objects",
163+
.tp_doc = PyDoc_STR("Custom objects"),
164164
.tp_basicsize = sizeof(CustomObject),
165165
.tp_itemsize = 0,
166166
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,

‎Doc/includes/sublist.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
3131
static PyTypeObject SubListType = {
3232
PyVarObject_HEAD_INIT(NULL, 0)
3333
.tp_name = "sublist.SubList",
34-
.tp_doc = "SubList objects",
34+
.tp_doc = PyDoc_STR("SubList objects"),
3535
.tp_basicsize = sizeof(SubListObject),
3636
.tp_itemsize = 0,
3737
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,

‎Misc/NEWS.d/next/Core and Builtins/2022-03-08-21-59-57.bpo-46962.UomDfz.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
Classes and functions that unconditionally declared their docstrings
2+
ignoring the `--without-doc-strings` compilation flag no longer do so.
3+
4+
The classes affected are :class:`pickle.PickleBuffer`,
5+
:class:`testcapi.RecursingInfinitelyError`, and :class:`types.GenericAlias`.
6+
7+
The functions affected are 24 methods in :mod:`ctypes`.
8+
9+
Patch by Oleg Iarygin.

‎Misc/NEWS.d/next/Documentation/2022-03-08-22-10-38.bpo-46962.FIVe9I.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
All docstrings in code snippets are now wrapped into :func:`PyDoc_STR` to
2+
follow the guideline of `PEP 7's Documentation Strings paragraph
3+
<https://www.python.org/dev/peps/pep-0007/#documentation-strings>`_. Patch
4+
by Oleg Iarygin.

‎Modules/_ctypes/_ctypes.c

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -181,7 +181,7 @@ static PyTypeObject DictRemover_Type = {
181181
0, /* tp_as_buffer */
182182
/* XXX should participate in GC? */
183183
Py_TPFLAGS_DEFAULT, /* tp_flags */
184-
"deletes a key from a dictionary", /* tp_doc */
184+
PyDoc_STR("deletes a key from a dictionary"), /* tp_doc */
185185
0, /* tp_traverse */
186186
0, /* tp_clear */
187187
0, /* tp_richcompare */
@@ -563,8 +563,8 @@ UnionType_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
563563
return StructUnionType_new(type, args, kwds, 0);
564564
}
565565

566-
static const char from_address_doc[] =
567-
"C.from_address(integer) -> C instance\naccess a C instance at the specified address";
566+
PyDoc_STRVAR(from_address_doc,
567+
"C.from_address(integer) -> C instance\naccess a C instance at the specified address");
568568

569569
static PyObject *
570570
CDataType_from_address(PyObject *type, PyObject *value)
@@ -581,8 +581,8 @@ CDataType_from_address(PyObject *type, PyObject *value)
581581
return PyCData_AtAddress(type, buf);
582582
}
583583

584-
static const char from_buffer_doc[] =
585-
"C.from_buffer(object, offset=0) -> C instance\ncreate a C instance from a writeable buffer";
584+
PyDoc_STRVAR(from_buffer_doc,
585+
"C.from_buffer(object, offset=0) -> C instance\ncreate a C instance from a writeable buffer");
586586

587587
static int
588588
KeepRef(CDataObject *target, Py_ssize_t index, PyObject *keep);
@@ -661,8 +661,8 @@ CDataType_from_buffer(PyObject *type, PyObject *args)
661661
return result;
662662
}
663663

664-
static const char from_buffer_copy_doc[] =
665-
"C.from_buffer_copy(object, offset=0) -> C instance\ncreate a C instance from a readable buffer";
664+
PyDoc_STRVAR(from_buffer_copy_doc,
665+
"C.from_buffer_copy(object, offset=0) -> C instance\ncreate a C instance from a readable buffer");
666666

667667
static PyObject *
668668
GenericPyCData_new(PyTypeObject *type, PyObject *args, PyObject *kwds);
@@ -712,8 +712,8 @@ CDataType_from_buffer_copy(PyObject *type, PyObject *args)
712712
return result;
713713
}
714714

715-
static const char in_dll_doc[] =
716-
"C.in_dll(dll, name) -> C instance\naccess a C instance in a dll";
715+
PyDoc_STRVAR(in_dll_doc,
716+
"C.in_dll(dll, name) -> C instance\naccess a C instance in a dll");
717717

718718
static PyObject *
719719
CDataType_in_dll(PyObject *type, PyObject *args)
@@ -774,8 +774,8 @@ CDataType_in_dll(PyObject *type, PyObject *args)
774774
return PyCData_AtAddress(type, address);
775775
}
776776

777-
static const char from_param_doc[] =
778-
"Convert a Python object into a function call parameter.";
777+
PyDoc_STRVAR(from_param_doc,
778+
"Convert a Python object into a function call parameter.");
779779

780780
static PyObject *
781781
CDataType_from_param(PyObject *type, PyObject *value)
@@ -929,7 +929,7 @@ PyTypeObject PyCStructType_Type = {
929929
PyCStructType_setattro, /* tp_setattro */
930930
0, /* tp_as_buffer */
931931
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
932-
"metatype for the CData Objects", /* tp_doc */
932+
PyDoc_STR("metatype for the CData Objects"), /* tp_doc */
933933
(traverseproc)CDataType_traverse, /* tp_traverse */
934934
(inquiry)CDataType_clear, /* tp_clear */
935935
0, /* tp_richcompare */
@@ -971,7 +971,7 @@ static PyTypeObject UnionType_Type = {
971971
UnionType_setattro, /* tp_setattro */
972972
0, /* tp_as_buffer */
973973
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
974-
"metatype for the CData Objects", /* tp_doc */
974+
PyDoc_STR("metatype for the CData Objects"), /* tp_doc */
975975
(traverseproc)CDataType_traverse, /* tp_traverse */
976976
(inquiry)CDataType_clear, /* tp_clear */
977977
0, /* tp_richcompare */
@@ -1229,7 +1229,7 @@ PyTypeObject PyCPointerType_Type = {
12291229
0, /* tp_setattro */
12301230
0, /* tp_as_buffer */
12311231
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
1232-
"metatype for the Pointer Objects", /* tp_doc */
1232+
PyDoc_STR("metatype for the Pointer Objects"), /* tp_doc */
12331233
(traverseproc)CDataType_traverse, /* tp_traverse */
12341234
(inquiry)CDataType_clear, /* tp_clear */
12351235
0, /* tp_richcompare */
@@ -1651,7 +1651,7 @@ PyTypeObject PyCArrayType_Type = {
16511651
0, /* tp_setattro */
16521652
0, /* tp_as_buffer */
16531653
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
1654-
"metatype for the Array Objects", /* tp_doc */
1654+
PyDoc_STR("metatype for the Array Objects"), /* tp_doc */
16551655
0, /* tp_traverse */
16561656
0, /* tp_clear */
16571657
0, /* tp_richcompare */
@@ -2345,7 +2345,7 @@ PyTypeObject PyCSimpleType_Type = {
23452345
0, /* tp_setattro */
23462346
0, /* tp_as_buffer */
23472347
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
2348-
"metatype for the PyCSimpleType Objects", /* tp_doc */
2348+
PyDoc_STR("metatype for the PyCSimpleType Objects"), /* tp_doc */
23492349
0, /* tp_traverse */
23502350
0, /* tp_clear */
23512351
0, /* tp_richcompare */
@@ -2627,7 +2627,7 @@ PyTypeObject PyCFuncPtrType_Type = {
26272627
0, /* tp_setattro */
26282628
0, /* tp_as_buffer */
26292629
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
2630-
"metatype for C function pointers", /* tp_doc */
2630+
PyDoc_STR("metatype for C function pointers"), /* tp_doc */
26312631
(traverseproc)CDataType_traverse, /* tp_traverse */
26322632
(inquiry)CDataType_clear, /* tp_clear */
26332633
0, /* tp_richcompare */
@@ -2932,7 +2932,7 @@ PyTypeObject PyCData_Type = {
29322932
0, /* tp_setattro */
29332933
&PyCData_as_buffer, /* tp_as_buffer */
29342934
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
2935-
"XXX to be provided", /* tp_doc */
2935+
PyDoc_STR("XXX to be provided"), /* tp_doc */
29362936
(traverseproc)PyCData_traverse, /* tp_traverse */
29372937
(inquiry)PyCData_clear, /* tp_clear */
29382938
0, /* tp_richcompare */
@@ -4327,7 +4327,7 @@ PyTypeObject PyCFuncPtr_Type = {
43274327
0, /* tp_setattro */
43284328
&PyCData_as_buffer, /* tp_as_buffer */
43294329
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
4330-
"Function Pointer", /* tp_doc */
4330+
PyDoc_STR("Function Pointer"), /* tp_doc */
43314331
(traverseproc)PyCFuncPtr_traverse, /* tp_traverse */
43324332
(inquiry)PyCFuncPtr_clear, /* tp_clear */
43334333
0, /* tp_richcompare */
@@ -4481,7 +4481,7 @@ static PyTypeObject Struct_Type = {
44814481
0, /* tp_setattro */
44824482
&PyCData_as_buffer, /* tp_as_buffer */
44834483
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
4484-
"Structure base class", /* tp_doc */
4484+
PyDoc_STR("Structure base class"), /* tp_doc */
44854485
(traverseproc)PyCData_traverse, /* tp_traverse */
44864486
(inquiry)PyCData_clear, /* tp_clear */
44874487
0, /* tp_richcompare */
@@ -4523,7 +4523,7 @@ static PyTypeObject Union_Type = {
45234523
0, /* tp_setattro */
45244524
&PyCData_as_buffer, /* tp_as_buffer */
45254525
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
4526-
"Union base class", /* tp_doc */
4526+
PyDoc_STR("Union base class"), /* tp_doc */
45274527
(traverseproc)PyCData_traverse, /* tp_traverse */
45284528
(inquiry)PyCData_clear, /* tp_clear */
45294529
0, /* tp_richcompare */
@@ -4845,7 +4845,7 @@ PyTypeObject PyCArray_Type = {
48454845
0, /* tp_setattro */
48464846
&PyCData_as_buffer, /* tp_as_buffer */
48474847
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
4848-
"XXX to be provided", /* tp_doc */
4848+
PyDoc_STR("XXX to be provided"), /* tp_doc */
48494849
(traverseproc)PyCData_traverse, /* tp_traverse */
48504850
(inquiry)PyCData_clear, /* tp_clear */
48514851
0, /* tp_richcompare */
@@ -5064,7 +5064,7 @@ static PyTypeObject Simple_Type = {
50645064
0, /* tp_setattro */
50655065
&PyCData_as_buffer, /* tp_as_buffer */
50665066
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
5067-
"XXX to be provided", /* tp_doc */
5067+
PyDoc_STR("XXX to be provided"), /* tp_doc */
50685068
(traverseproc)PyCData_traverse, /* tp_traverse */
50695069
(inquiry)PyCData_clear, /* tp_clear */
50705070
0, /* tp_richcompare */
@@ -5448,7 +5448,7 @@ PyTypeObject PyCPointer_Type = {
54485448
0, /* tp_setattro */
54495449
&PyCData_as_buffer, /* tp_as_buffer */
54505450
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
5451-
"XXX to be provided", /* tp_doc */
5451+
PyDoc_STR("XXX to be provided"), /* tp_doc */
54525452
(traverseproc)PyCData_traverse, /* tp_traverse */
54535453
(inquiry)PyCData_clear, /* tp_clear */
54545454
0, /* tp_richcompare */
@@ -5475,12 +5475,12 @@ PyTypeObject PyCPointer_Type = {
54755475
* Module initialization.
54765476
*/
54775477

5478-
static const char module_docs[] =
5479-
"Create and manipulate C compatible data types in Python.";
5478+
PyDoc_STRVAR(module_docs,
5479+
"Create and manipulate C compatible data types in Python.");
54805480

54815481
#ifdef MS_WIN32
54825482

5483-
static const char comerror_doc[] = "Raised when a COM method call failed.";
5483+
PyDoc_STRVAR(comerror_doc, "Raised when a COM method call failed.");
54845484

54855485
int
54865486
comerror_init(PyObject *self, PyObject *args, PyObject *kwds)

‎Modules/_ctypes/callbacks.c

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ PyTypeObject PyCThunk_Type = {
6565
0, /* tp_setattro */
6666
0, /* tp_as_buffer */
6767
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, /* tp_flags */
68-
"CThunkObject", /* tp_doc */
68+
PyDoc_STR("CThunkObject"), /* tp_doc */
6969
CThunkObject_traverse, /* tp_traverse */
7070
CThunkObject_clear, /* tp_clear */
7171
0, /* tp_richcompare */

0 commit comments

Comments
 (0)