Skip to content

Commit e7e8a9f

Browse files
arhadthedevarhadthedev
authored
[3.10] gh-91118: Fix docstrings that do not honor --without-doc-strings (GH-31769) (#91662)
Co-authored-by: Éric <[email protected]> Co-authored-by: Jelle Zijlstra <[email protected]> (cherry picked from commit a573cb2) Co-authored-by: Oleg Iarygin <[email protected]>
1 parent a885f10 commit e7e8a9f

File tree

17 files changed

+81
-65
lines changed

17 files changed

+81
-65
lines changed

‎Doc/c-api/typeobj.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2596,7 +2596,7 @@ A basic :ref:`static type <static-types>`::
25962596
PyVarObject_HEAD_INIT(NULL, 0)
25972597
.tp_name = "mymod.MyObject",
25982598
.tp_basicsize = sizeof(MyObject),
2599-
.tp_doc = "My objects",
2599+
.tp_doc = PyDoc_STR("My objects"),
26002600
.tp_new = myobj_new,
26012601
.tp_dealloc = (destructor)myobj_dealloc,
26022602
.tp_repr = (reprfunc)myobj_repr,
@@ -2626,7 +2626,7 @@ with a more verbose initializer::
26262626
0, /* tp_setattro */
26272627
0, /* tp_as_buffer */
26282628
0, /* tp_flags */
2629-
"My objects", /* tp_doc */
2629+
PyDoc_STR("My objects"), /* tp_doc */
26302630
0, /* tp_traverse */
26312631
0, /* tp_clear */
26322632
0, /* tp_richcompare */
@@ -2659,7 +2659,7 @@ A type that supports weakrefs, instance dicts, and hashing::
26592659
PyVarObject_HEAD_INIT(NULL, 0)
26602660
.tp_name = "mymod.MyObject",
26612661
.tp_basicsize = sizeof(MyObject),
2662-
.tp_doc = "My objects",
2662+
.tp_doc = PyDoc_STR("My objects"),
26632663
.tp_weaklistoffset = offsetof(MyObject, weakreflist),
26642664
.tp_dictoffset = offsetof(MyObject, inst_dict),
26652665
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
@@ -2687,7 +2687,7 @@ to create instances (e.g. uses a separate factory func) using
26872687
.tp_name = "mymod.MyStr",
26882688
.tp_basicsize = sizeof(MyStr),
26892689
.tp_base = NULL, // set to &PyUnicode_Type in module init
2690-
.tp_doc = "my custom str",
2690+
.tp_doc = PyDoc_STR("my custom str"),
26912691
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_DISALLOW_INSTANTIATION,
26922692
.tp_repr = (reprfunc)myobj_repr,
26932693
};

‎Doc/extending/newtypes_tutorial.rst‎

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

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

164-
.tp_doc = "Custom objects",
164+
.tp_doc = PyDoc_STR("Custom objects"),
165165

166166
To enable object creation, we have to provide a :c:member:`~PyTypeObject.tp_new`
167167
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: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
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:`ctypes.UnionType`,
5+
:class:`pickle.PickleBuffer`, :class:`testcapi.RecursingInfinitelyError`,
6+
and :class:`types.GenericAlias`.
7+
8+
The functions affected are 24 methods in :mod:`ctypes`.
9+
10+
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: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -187,7 +187,7 @@ static PyTypeObject DictRemover_Type = {
187187
0, /* tp_as_buffer */
188188
/* XXX should participate in GC? */
189189
Py_TPFLAGS_DEFAULT, /* tp_flags */
190-
"deletes a key from a dictionary", /* tp_doc */
190+
PyDoc_STR("deletes a key from a dictionary"), /* tp_doc */
191191
0, /* tp_traverse */
192192
0, /* tp_clear */
193193
0, /* tp_richcompare */
@@ -570,8 +570,8 @@ UnionType_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
570570
return StructUnionType_new(type, args, kwds, 0);
571571
}
572572

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

576576
static PyObject *
577577
CDataType_from_address(PyObject *type, PyObject *value)
@@ -588,8 +588,8 @@ CDataType_from_address(PyObject *type, PyObject *value)
588588
return PyCData_AtAddress(type, buf);
589589
}
590590

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

594594
static int
595595
KeepRef(CDataObject *target, Py_ssize_t index, PyObject *keep);
@@ -668,8 +668,8 @@ CDataType_from_buffer(PyObject *type, PyObject *args)
668668
return result;
669669
}
670670

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

674674
static PyObject *
675675
GenericPyCData_new(PyTypeObject *type, PyObject *args, PyObject *kwds);
@@ -719,8 +719,8 @@ CDataType_from_buffer_copy(PyObject *type, PyObject *args)
719719
return result;
720720
}
721721

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

725725
static PyObject *
726726
CDataType_in_dll(PyObject *type, PyObject *args)
@@ -781,8 +781,8 @@ CDataType_in_dll(PyObject *type, PyObject *args)
781781
return PyCData_AtAddress(type, address);
782782
}
783783

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

787787
static PyObject *
788788
CDataType_from_param(PyObject *type, PyObject *value)
@@ -936,7 +936,7 @@ PyTypeObject PyCStructType_Type = {
936936
PyCStructType_setattro, /* tp_setattro */
937937
0, /* tp_as_buffer */
938938
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
939-
"metatype for the CData Objects", /* tp_doc */
939+
PyDoc_STR("metatype for the CData Objects"), /* tp_doc */
940940
(traverseproc)CDataType_traverse, /* tp_traverse */
941941
(inquiry)CDataType_clear, /* tp_clear */
942942
0, /* tp_richcompare */
@@ -978,7 +978,7 @@ static PyTypeObject UnionType_Type = {
978978
UnionType_setattro, /* tp_setattro */
979979
0, /* tp_as_buffer */
980980
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
981-
"metatype for the CData Objects", /* tp_doc */
981+
PyDoc_STR("metatype for the CData Objects"), /* tp_doc */
982982
(traverseproc)CDataType_traverse, /* tp_traverse */
983983
(inquiry)CDataType_clear, /* tp_clear */
984984
0, /* tp_richcompare */
@@ -1236,7 +1236,7 @@ PyTypeObject PyCPointerType_Type = {
12361236
0, /* tp_setattro */
12371237
0, /* tp_as_buffer */
12381238
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
1239-
"metatype for the Pointer Objects", /* tp_doc */
1239+
PyDoc_STR("metatype for the Pointer Objects"), /* tp_doc */
12401240
(traverseproc)CDataType_traverse, /* tp_traverse */
12411241
(inquiry)CDataType_clear, /* tp_clear */
12421242
0, /* tp_richcompare */
@@ -1648,7 +1648,7 @@ PyTypeObject PyCArrayType_Type = {
16481648
0, /* tp_setattro */
16491649
0, /* tp_as_buffer */
16501650
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
1651-
"metatype for the Array Objects", /* tp_doc */
1651+
PyDoc_STR("metatype for the Array Objects"), /* tp_doc */
16521652
0, /* tp_traverse */
16531653
0, /* tp_clear */
16541654
0, /* tp_richcompare */
@@ -2342,7 +2342,7 @@ PyTypeObject PyCSimpleType_Type = {
23422342
0, /* tp_setattro */
23432343
0, /* tp_as_buffer */
23442344
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
2345-
"metatype for the PyCSimpleType Objects", /* tp_doc */
2345+
PyDoc_STR("metatype for the PyCSimpleType Objects"), /* tp_doc */
23462346
0, /* tp_traverse */
23472347
0, /* tp_clear */
23482348
0, /* tp_richcompare */
@@ -2624,7 +2624,7 @@ PyTypeObject PyCFuncPtrType_Type = {
26242624
0, /* tp_setattro */
26252625
0, /* tp_as_buffer */
26262626
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */
2627-
"metatype for C function pointers", /* tp_doc */
2627+
PyDoc_STR("metatype for C function pointers"), /* tp_doc */
26282628
(traverseproc)CDataType_traverse, /* tp_traverse */
26292629
(inquiry)CDataType_clear, /* tp_clear */
26302630
0, /* tp_richcompare */
@@ -2929,7 +2929,7 @@ PyTypeObject PyCData_Type = {
29292929
0, /* tp_setattro */
29302930
&PyCData_as_buffer, /* tp_as_buffer */
29312931
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
2932-
"XXX to be provided", /* tp_doc */
2932+
PyDoc_STR("XXX to be provided"), /* tp_doc */
29332933
(traverseproc)PyCData_traverse, /* tp_traverse */
29342934
(inquiry)PyCData_clear, /* tp_clear */
29352935
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 */
@@ -4479,7 +4479,7 @@ static PyTypeObject Struct_Type = {
44794479
0, /* tp_setattro */
44804480
&PyCData_as_buffer, /* tp_as_buffer */
44814481
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
4482-
"Structure base class", /* tp_doc */
4482+
PyDoc_STR("Structure base class"), /* tp_doc */
44834483
(traverseproc)PyCData_traverse, /* tp_traverse */
44844484
(inquiry)PyCData_clear, /* tp_clear */
44854485
0, /* tp_richcompare */
@@ -4521,7 +4521,7 @@ static PyTypeObject Union_Type = {
45214521
0, /* tp_setattro */
45224522
&PyCData_as_buffer, /* tp_as_buffer */
45234523
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
4524-
"Union base class", /* tp_doc */
4524+
PyDoc_STR("Union base class"), /* tp_doc */
45254525
(traverseproc)PyCData_traverse, /* tp_traverse */
45264526
(inquiry)PyCData_clear, /* tp_clear */
45274527
0, /* tp_richcompare */
@@ -4841,7 +4841,7 @@ PyTypeObject PyCArray_Type = {
48414841
0, /* tp_setattro */
48424842
&PyCData_as_buffer, /* tp_as_buffer */
48434843
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
4844-
"XXX to be provided", /* tp_doc */
4844+
PyDoc_STR("XXX to be provided"), /* tp_doc */
48454845
(traverseproc)PyCData_traverse, /* tp_traverse */
48464846
(inquiry)PyCData_clear, /* tp_clear */
48474847
0, /* tp_richcompare */
@@ -5060,7 +5060,7 @@ static PyTypeObject Simple_Type = {
50605060
0, /* tp_setattro */
50615061
&PyCData_as_buffer, /* tp_as_buffer */
50625062
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
5063-
"XXX to be provided", /* tp_doc */
5063+
PyDoc_STR("XXX to be provided"), /* tp_doc */
50645064
(traverseproc)PyCData_traverse, /* tp_traverse */
50655065
(inquiry)PyCData_clear, /* tp_clear */
50665066
0, /* tp_richcompare */
@@ -5442,7 +5442,7 @@ PyTypeObject PyCPointer_Type = {
54425442
0, /* tp_setattro */
54435443
&PyCData_as_buffer, /* tp_as_buffer */
54445444
Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, /* tp_flags */
5445-
"XXX to be provided", /* tp_doc */
5445+
PyDoc_STR("XXX to be provided"), /* tp_doc */
54465446
(traverseproc)PyCData_traverse, /* tp_traverse */
54475447
(inquiry)PyCData_clear, /* tp_clear */
54485448
0, /* tp_richcompare */
@@ -5469,12 +5469,12 @@ PyTypeObject PyCPointer_Type = {
54695469
* Module initialization.
54705470
*/
54715471

5472-
static const char module_docs[] =
5473-
"Create and manipulate C compatible data types in Python.";
5472+
PyDoc_STRVAR(_ctypes__doc__,
5473+
"Create and manipulate C compatible data types in Python.");
54745474

54755475
#ifdef MS_WIN32
54765476

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

54795479
int
54805480
comerror_init(PyObject *self, PyObject *args, PyObject *kwds)
@@ -5663,7 +5663,7 @@ wstring_at(const wchar_t *ptr, int size)
56635663
static struct PyModuleDef _ctypesmodule = {
56645664
PyModuleDef_HEAD_INIT,
56655665
.m_name = "_ctypes",
5666-
.m_doc = module_docs,
5666+
.m_doc = _ctypes__doc__,
56675667
.m_size = -1,
56685668
.m_methods = _ctypes_module_methods,
56695669
};

0 commit comments

Comments
 (0)