Issue #20530: Argument Clinic's signature format has been revised again.

The new syntax is highly human readable while still preventing false
positives.  The syntax also extends Python syntax to denote "self" and
positional-only parameters, allowing inspect.Signature objects to be
totally accurate for all supported builtins in Python 3.4.

6 files changed, 251 insertions, 86 deletions

diff --git a/Modules/clinic/_bz2module.c.h b/Modules/clinic/_bz2module.c.h
index 98f9a1b88d..8a201a08de 100644
--- a/Modules/clinic/_bz2module.c.h
+++ b/Modules/clinic/_bz2module.c.h
@@ -3,7 +3,9 @@ preserve
 [clinic start generated code]*/
 
 PyDoc_STRVAR(_bz2_BZ2Compressor_compress__doc__,
-"sig=($self, data)\n"
+"compress($self, data, /)\n"
+"--\n"
+"\n"
 "Provide data to the compressor object.\n"
 "\n"
 "Returns a chunk of compressed data if possible, or b\'\' otherwise.\n"
@@ -38,7 +40,9 @@ exit:
 }
 
 PyDoc_STRVAR(_bz2_BZ2Compressor_flush__doc__,
-"sig=($self)\n"
+"flush($self, /)\n"
+"--\n"
+"\n"
 "Finish the compression process.\n"
 "\n"
 "Returns the compressed data left in internal buffers.\n"
@@ -58,7 +62,9 @@ _bz2_BZ2Compressor_flush(BZ2Compressor *self, PyObject *Py_UNUSED(ignored))
 }
 
 PyDoc_STRVAR(_bz2_BZ2Compressor___init____doc__,
-"sig=(compresslevel=9)\n"
+"BZ2Compressor(compresslevel=9, /)\n"
+"--\n"
+"\n"
 "Create a compressor object for compressing data incrementally.\n"
 "\n"
 "  compresslevel\n"
@@ -89,7 +95,9 @@ exit:
 }
 
 PyDoc_STRVAR(_bz2_BZ2Decompressor_decompress__doc__,
-"sig=($self, data)\n"
+"decompress($self, data, /)\n"
+"--\n"
+"\n"
 "Provide data to the decompressor object.\n"
 "\n"
 "Returns a chunk of decompressed data if possible, or b\'\' otherwise.\n"
@@ -125,7 +133,9 @@ exit:
 }
 
 PyDoc_STRVAR(_bz2_BZ2Decompressor___init____doc__,
-"sig=()\n"
+"BZ2Decompressor()\n"
+"--\n"
+"\n"
 "Create a decompressor object for decompressing data incrementally.\n"
 "\n"
 "For one-shot decompression, use the decompress() function instead.");
@@ -149,4 +159,4 @@ _bz2_BZ2Decompressor___init__(PyObject *self, PyObject *args, PyObject *kwargs)
 exit:
     return return_value;
 }
-/*[clinic end generated code: output=aca4f6329c1c773a input=a9049054013a1b77]*/
+/*[clinic end generated code: output=21ca4405519a0931 input=a9049054013a1b77]*/
diff --git a/Modules/clinic/_lzmamodule.c.h b/Modules/clinic/_lzmamodule.c.h
index 184889185c..c1ad8824af 100644
--- a/Modules/clinic/_lzmamodule.c.h
+++ b/Modules/clinic/_lzmamodule.c.h
@@ -3,7 +3,9 @@ preserve
 [clinic start generated code]*/
 
 PyDoc_STRVAR(_lzma_LZMACompressor_compress__doc__,
-"sig=($self, data)\n"
+"compress($self, data, /)\n"
+"--\n"
+"\n"
 "Provide data to the compressor object.\n"
 "\n"
 "Returns a chunk of compressed data if possible, or b\'\' otherwise.\n"
@@ -38,7 +40,9 @@ exit:
 }
 
 PyDoc_STRVAR(_lzma_LZMACompressor_flush__doc__,
-"sig=($self)\n"
+"flush($self, /)\n"
+"--\n"
+"\n"
 "Finish the compression process.\n"
 "\n"
 "Returns the compressed data left in internal buffers.\n"
@@ -58,7 +62,9 @@ _lzma_LZMACompressor_flush(Compressor *self, PyObject *Py_UNUSED(ignored))
 }
 
 PyDoc_STRVAR(_lzma_LZMADecompressor_decompress__doc__,
-"sig=($self, data)\n"
+"decompress($self, data, /)\n"
+"--\n"
+"\n"
 "Provide data to the decompressor object.\n"
 "\n"
 "Returns a chunk of decompressed data if possible, or b\'\' otherwise.\n"
@@ -94,7 +100,9 @@ exit:
 }
 
 PyDoc_STRVAR(_lzma_LZMADecompressor___init____doc__,
-"sig=(format=FORMAT_AUTO, memlimit=None, filters=None)\n"
+"LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)\n"
+"--\n"
+"\n"
 "Create a decompressor object for decompressing data incrementally.\n"
 "\n"
 "  format\n"
@@ -137,7 +145,9 @@ exit:
 }
 
 PyDoc_STRVAR(_lzma_is_check_supported__doc__,
-"sig=($module, check_id)\n"
+"is_check_supported($module, check_id, /)\n"
+"--\n"
+"\n"
 "Test whether the given integrity check is supported.\n"
 "\n"
 "Always returns True for CHECK_NONE and CHECK_CRC32.");
@@ -165,7 +175,9 @@ exit:
 }
 
 PyDoc_STRVAR(_lzma__encode_filter_properties__doc__,
-"sig=($module, filter)\n"
+"_encode_filter_properties($module, filter, /)\n"
+"--\n"
+"\n"
 "Return a bytes object encoding the options (properties) of the filter specified by *filter* (a dict).\n"
 "\n"
 "The result does not include the filter ID itself, only the options.");
@@ -197,7 +209,9 @@ exit:
 }
 
 PyDoc_STRVAR(_lzma__decode_filter_properties__doc__,
-"sig=($module, filter_id, encoded_props)\n"
+"_decode_filter_properties($module, filter_id, encoded_props, /)\n"
+"--\n"
+"\n"
 "Return a bytes object encoding the options (properties) of the filter specified by *filter* (a dict).\n"
 "\n"
 "The result does not include the filter ID itself, only the options.");
@@ -228,4 +242,4 @@ exit:
 
     return return_value;
 }
-/*[clinic end generated code: output=fe63bc798a5c5c55 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=808fec8216ac712b input=a9049054013a1b77]*/
diff --git a/Modules/clinic/_pickle.c.h b/Modules/clinic/_pickle.c.h
index 9ef469dc40..a20a61e6f5 100644
--- a/Modules/clinic/_pickle.c.h
+++ b/Modules/clinic/_pickle.c.h
@@ -3,7 +3,9 @@ preserve
 [clinic start generated code]*/
 
 PyDoc_STRVAR(_pickle_Pickler_clear_memo__doc__,
-"sig=($self)\n"
+"clear_memo($self, /)\n"
+"--\n"
+"\n"
 "Clears the pickler\'s \"memo\".\n"
 "\n"
 "The memo is the data structure that remembers which objects the\n"
@@ -24,14 +26,18 @@ _pickle_Pickler_clear_memo(PicklerObject *self, PyObject *Py_UNUSED(ignored))
 }
 
 PyDoc_STRVAR(_pickle_Pickler_dump__doc__,
-"sig=($self, obj)\n"
+"dump($self, obj, /)\n"
+"--\n"
+"\n"
 "Write a pickled representation of the given object to the open file.");
 
 #define _PICKLE_PICKLER_DUMP_METHODDEF    \
     {"dump", (PyCFunction)_pickle_Pickler_dump, METH_O, _pickle_Pickler_dump__doc__},
 
 PyDoc_STRVAR(_pickle_Pickler___init____doc__,
-"sig=(file, protocol=None, fix_imports=True)\n"
+"Pickler(file, protocol=None, fix_imports=True)\n"
+"--\n"
+"\n"
 "This takes a binary file for writing a pickle data stream.\n"
 "\n"
 "The optional *protocol* argument tells the pickler to use the given\n"
@@ -74,7 +80,9 @@ exit:
 }
 
 PyDoc_STRVAR(_pickle_PicklerMemoProxy_clear__doc__,
-"sig=($self)\n"
+"clear($self, /)\n"
+"--\n"
+"\n"
 "Remove all items from memo.");
 
 #define _PICKLE_PICKLERMEMOPROXY_CLEAR_METHODDEF    \
@@ -90,7 +98,9 @@ _pickle_PicklerMemoProxy_clear(PicklerMemoProxyObject *self, PyObject *Py_UNUSED
 }
 
 PyDoc_STRVAR(_pickle_PicklerMemoProxy_copy__doc__,
-"sig=($self)\n"
+"copy($self, /)\n"
+"--\n"
+"\n"
 "Copy the memo to a new object.");
 
 #define _PICKLE_PICKLERMEMOPROXY_COPY_METHODDEF    \
@@ -106,7 +116,9 @@ _pickle_PicklerMemoProxy_copy(PicklerMemoProxyObject *self, PyObject *Py_UNUSED(
 }
 
 PyDoc_STRVAR(_pickle_PicklerMemoProxy___reduce____doc__,
-"sig=($self)\n"
+"__reduce__($self, /)\n"
+"--\n"
+"\n"
 "Implement pickle support.");
 
 #define _PICKLE_PICKLERMEMOPROXY___REDUCE___METHODDEF    \
@@ -122,7 +134,9 @@ _pickle_PicklerMemoProxy___reduce__(PicklerMemoProxyObject *self, PyObject *Py_U
 }
 
 PyDoc_STRVAR(_pickle_Unpickler_load__doc__,
-"sig=($self)\n"
+"load($self, /)\n"
+"--\n"
+"\n"
 "Load a pickle.\n"
 "\n"
 "Read a pickled object representation from the open file object given\n"
@@ -142,7 +156,9 @@ _pickle_Unpickler_load(UnpicklerObject *self, PyObject *Py_UNUSED(ignored))
 }
 
 PyDoc_STRVAR(_pickle_Unpickler_find_class__doc__,
-"sig=($self, module_name, global_name)\n"
+"find_class($self, module_name, global_name, /)\n"
+"--\n"
+"\n"
 "Return an object from a specified module.\n"
 "\n"
 "If necessary, the module will be imported. Subclasses may override\n"
@@ -176,7 +192,9 @@ exit:
 }
 
 PyDoc_STRVAR(_pickle_Unpickler___init____doc__,
-"sig=(file, *, fix_imports=True, encoding=\'ASCII\', errors=\'strict\')\n"
+"Unpickler(file, *, fix_imports=True, encoding=\'ASCII\', errors=\'strict\')\n"
+"--\n"
+"\n"
 "This takes a binary file for reading a pickle data stream.\n"
 "\n"
 "The protocol version of the pickle is detected automatically, so no\n"
@@ -222,7 +240,9 @@ exit:
 }
 
 PyDoc_STRVAR(_pickle_UnpicklerMemoProxy_clear__doc__,
-"sig=($self)\n"
+"clear($self, /)\n"
+"--\n"
+"\n"
 "Remove all items from memo.");
 
 #define _PICKLE_UNPICKLERMEMOPROXY_CLEAR_METHODDEF    \
@@ -238,7 +258,9 @@ _pickle_UnpicklerMemoProxy_clear(UnpicklerMemoProxyObject *self, PyObject *Py_UN
 }
 
 PyDoc_STRVAR(_pickle_UnpicklerMemoProxy_copy__doc__,
-"sig=($self)\n"
+"copy($self, /)\n"
+"--\n"
+"\n"
 "Copy the memo to a new object.");
 
 #define _PICKLE_UNPICKLERMEMOPROXY_COPY_METHODDEF    \
@@ -254,7 +276,9 @@ _pickle_UnpicklerMemoProxy_copy(UnpicklerMemoProxyObject *self, PyObject *Py_UNU
 }
 
 PyDoc_STRVAR(_pickle_UnpicklerMemoProxy___reduce____doc__,
-"sig=($self)\n"
+"__reduce__($self, /)\n"
+"--\n"
+"\n"
 "Implement pickling support.");
 
 #define _PICKLE_UNPICKLERMEMOPROXY___REDUCE___METHODDEF    \
@@ -270,7 +294,9 @@ _pickle_UnpicklerMemoProxy___reduce__(UnpicklerMemoProxyObject *self, PyObject *
 }
 
 PyDoc_STRVAR(_pickle_dump__doc__,
-"sig=($module, obj, file, protocol=None, *, fix_imports=True)\n"
+"dump($module, /, obj, file, protocol=None, *, fix_imports=True)\n"
+"--\n"
+"\n"
 "Write a pickled representation of obj to the open file object file.\n"
 "\n"
 "This is equivalent to ``Pickler(file, protocol).dump(obj)``, but may\n"
@@ -320,7 +346,9 @@ exit:
 }
 
 PyDoc_STRVAR(_pickle_dumps__doc__,
-"sig=($module, obj, protocol=None, *, fix_imports=True)\n"
+"dumps($module, /, obj, protocol=None, *, fix_imports=True)\n"
+"--\n"
+"\n"
 "Return the pickled representation of the object as a bytes object.\n"
 "\n"
 "The optional *protocol* argument tells the pickler to use the given\n"
@@ -361,7 +389,10 @@ exit:
 }
 
 PyDoc_STRVAR(_pickle_load__doc__,
-"sig=($module, file, *, fix_imports=True, encoding=\'ASCII\', errors=\'strict\')\n"
+"load($module, /, file, *, fix_imports=True, encoding=\'ASCII\',\n"
+"     errors=\'strict\')\n"
+"--\n"
+"\n"
 "Read and return an object from the pickle data stored in a file.\n"
 "\n"
 "This is equivalent to ``Unpickler(file).load()``, but may be more\n"
@@ -413,7 +444,10 @@ exit:
 }
 
 PyDoc_STRVAR(_pickle_loads__doc__,
-"sig=($module, data, *, fix_imports=True, encoding=\'ASCII\', errors=\'strict\')\n"
+"loads($module, /, data, *, fix_imports=True, encoding=\'ASCII\',\n"
+"      errors=\'strict\')\n"
+"--\n"
+"\n"
 "Read and return an object from the given pickle data.\n"
 "\n"
 "The protocol version of the pickle is detected automatically, so no\n"
@@ -454,4 +488,4 @@ _pickle_loads(PyModuleDef *module, PyObject *args, PyObject *kwargs)
 exit:
     return return_value;
 }
-/*[clinic end generated code: output=c59d4dafc2646f11 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=f965b6c7018c898d input=a9049054013a1b77]*/
diff --git a/Modules/clinic/audioop.c.h b/Modules/clinic/audioop.c.h
index 92d13b091d..40ef5e2dc4 100644
--- a/Modules/clinic/audioop.c.h
+++ b/Modules/clinic/audioop.c.h
@@ -3,7 +3,9 @@ preserve
 [clinic start generated code]*/
 
 PyDoc_STRVAR(audioop_getsample__doc__,
-"sig=($module, fragment, width, index)\n"
+"getsample($module, fragment, width, index, /)\n"
+"--\n"
+"\n"
 "Return the value of sample index from the fragment.");
 
 #define AUDIOOP_GETSAMPLE_METHODDEF    \
@@ -35,7 +37,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_max__doc__,
-"sig=($module, fragment, width)\n"
+"max($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Return the maximum of the absolute value of all samples in a fragment.");
 
 #define AUDIOOP_MAX_METHODDEF    \
@@ -66,7 +70,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_minmax__doc__,
-"sig=($module, fragment, width)\n"
+"minmax($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Return the minimum and maximum values of all samples in the sound fragment.");
 
 #define AUDIOOP_MINMAX_METHODDEF    \
@@ -97,7 +103,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_avg__doc__,
-"sig=($module, fragment, width)\n"
+"avg($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Return the average over all samples in the fragment.");
 
 #define AUDIOOP_AVG_METHODDEF    \
@@ -128,7 +136,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_rms__doc__,
-"sig=($module, fragment, width)\n"
+"rms($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Return the root-mean-square of the fragment, i.e. sqrt(sum(S_i^2)/n).");
 
 #define AUDIOOP_RMS_METHODDEF    \
@@ -159,7 +169,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_findfit__doc__,
-"sig=($module, fragment, reference)\n"
+"findfit($module, fragment, reference, /)\n"
+"--\n"
+"\n"
 "Try to match reference as well as possible to a portion of fragment.");
 
 #define AUDIOOP_FINDFIT_METHODDEF    \
@@ -193,7 +205,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_findfactor__doc__,
-"sig=($module, fragment, reference)\n"
+"findfactor($module, fragment, reference, /)\n"
+"--\n"
+"\n"
 "Return a factor F such that rms(add(fragment, mul(reference, -F))) is minimal.");
 
 #define AUDIOOP_FINDFACTOR_METHODDEF    \
@@ -227,7 +241,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_findmax__doc__,
-"sig=($module, fragment, length)\n"
+"findmax($module, fragment, length, /)\n"
+"--\n"
+"\n"
 "Search fragment for a slice of specified number of samples with maximum energy.");
 
 #define AUDIOOP_FINDMAX_METHODDEF    \
@@ -258,7 +274,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_avgpp__doc__,
-"sig=($module, fragment, width)\n"
+"avgpp($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Return the average peak-peak value over all samples in the fragment.");
 
 #define AUDIOOP_AVGPP_METHODDEF    \
@@ -289,7 +307,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_maxpp__doc__,
-"sig=($module, fragment, width)\n"
+"maxpp($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Return the maximum peak-peak value in the sound fragment.");
 
 #define AUDIOOP_MAXPP_METHODDEF    \
@@ -320,7 +340,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_cross__doc__,
-"sig=($module, fragment, width)\n"
+"cross($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Return the number of zero crossings in the fragment passed as an argument.");
 
 #define AUDIOOP_CROSS_METHODDEF    \
@@ -351,7 +373,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_mul__doc__,
-"sig=($module, fragment, width, factor)\n"
+"mul($module, fragment, width, factor, /)\n"
+"--\n"
+"\n"
 "Return a fragment that has all samples in the original fragment multiplied by the floating-point value factor.");
 
 #define AUDIOOP_MUL_METHODDEF    \
@@ -383,7 +407,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_tomono__doc__,
-"sig=($module, fragment, width, lfactor, rfactor)\n"
+"tomono($module, fragment, width, lfactor, rfactor, /)\n"
+"--\n"
+"\n"
 "Convert a stereo fragment to a mono fragment.");
 
 #define AUDIOOP_TOMONO_METHODDEF    \
@@ -416,7 +442,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_tostereo__doc__,
-"sig=($module, fragment, width, lfactor, rfactor)\n"
+"tostereo($module, fragment, width, lfactor, rfactor, /)\n"
+"--\n"
+"\n"
 "Generate a stereo fragment from a mono fragment.");
 
 #define AUDIOOP_TOSTEREO_METHODDEF    \
@@ -449,7 +477,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_add__doc__,
-"sig=($module, fragment1, fragment2, width)\n"
+"add($module, fragment1, fragment2, width, /)\n"
+"--\n"
+"\n"
 "Return a fragment which is the addition of the two samples passed as parameters.");
 
 #define AUDIOOP_ADD_METHODDEF    \
@@ -484,7 +514,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_bias__doc__,
-"sig=($module, fragment, width, bias)\n"
+"bias($module, fragment, width, bias, /)\n"
+"--\n"
+"\n"
 "Return a fragment that is the original fragment with a bias added to each sample.");
 
 #define AUDIOOP_BIAS_METHODDEF    \
@@ -516,7 +548,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_reverse__doc__,
-"sig=($module, fragment, width)\n"
+"reverse($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Reverse the samples in a fragment and returns the modified fragment.");
 
 #define AUDIOOP_REVERSE_METHODDEF    \
@@ -547,7 +581,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_byteswap__doc__,
-"sig=($module, fragment, width)\n"
+"byteswap($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Convert big-endian samples to little-endian and vice versa.");
 
 #define AUDIOOP_BYTESWAP_METHODDEF    \
@@ -578,7 +614,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_lin2lin__doc__,
-"sig=($module, fragment, width, newwidth)\n"
+"lin2lin($module, fragment, width, newwidth, /)\n"
+"--\n"
+"\n"
 "Convert samples between 1-, 2-, 3- and 4-byte formats.");
 
 #define AUDIOOP_LIN2LIN_METHODDEF    \
@@ -610,7 +648,10 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_ratecv__doc__,
-"sig=($module, fragment, width, nchannels, inrate, outrate, state, weightA=1, weightB=0)\n"
+"ratecv($module, fragment, width, nchannels, inrate, outrate, state,\n"
+"       weightA=1, weightB=0, /)\n"
+"--\n"
+"\n"
 "Convert the frame rate of the input fragment.");
 
 #define AUDIOOP_RATECV_METHODDEF    \
@@ -647,7 +688,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_lin2ulaw__doc__,
-"sig=($module, fragment, width)\n"
+"lin2ulaw($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Convert samples in the audio fragment to u-LAW encoding.");
 
 #define AUDIOOP_LIN2ULAW_METHODDEF    \
@@ -678,7 +721,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_ulaw2lin__doc__,
-"sig=($module, fragment, width)\n"
+"ulaw2lin($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Convert sound fragments in u-LAW encoding to linearly encoded sound fragments.");
 
 #define AUDIOOP_ULAW2LIN_METHODDEF    \
@@ -709,7 +754,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_lin2alaw__doc__,
-"sig=($module, fragment, width)\n"
+"lin2alaw($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Convert samples in the audio fragment to a-LAW encoding.");
 
 #define AUDIOOP_LIN2ALAW_METHODDEF    \
@@ -740,7 +787,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_alaw2lin__doc__,
-"sig=($module, fragment, width)\n"
+"alaw2lin($module, fragment, width, /)\n"
+"--\n"
+"\n"
 "Convert sound fragments in a-LAW encoding to linearly encoded sound fragments.");
 
 #define AUDIOOP_ALAW2LIN_METHODDEF    \
@@ -771,7 +820,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_lin2adpcm__doc__,
-"sig=($module, fragment, width, state)\n"
+"lin2adpcm($module, fragment, width, state, /)\n"
+"--\n"
+"\n"
 "Convert samples to 4 bit Intel/DVI ADPCM encoding.");
 
 #define AUDIOOP_LIN2ADPCM_METHODDEF    \
@@ -803,7 +854,9 @@ exit:
 }
 
 PyDoc_STRVAR(audioop_adpcm2lin__doc__,
-"sig=($module, fragment, width, state)\n"
+"adpcm2lin($module, fragment, width, state, /)\n"
+"--\n"
+"\n"
 "Decode an Intel/DVI ADPCM coded fragment to a linear fragment.");
 
 #define AUDIOOP_ADPCM2LIN_METHODDEF    \
@@ -833,4 +886,4 @@ exit:
 
     return return_value;
 }
-/*[clinic end generated code: output=ee7e58cfd3d0d5a6 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=be840bba5d40c2ce input=a9049054013a1b77]*/
diff --git a/Modules/clinic/binascii.c.h b/Modules/clinic/binascii.c.h
index e4ef36c960..5247180a41 100644
--- a/Modules/clinic/binascii.c.h
+++ b/Modules/clinic/binascii.c.h
@@ -3,7 +3,9 @@ preserve
 [clinic start generated code]*/
 
 PyDoc_STRVAR(binascii_a2b_uu__doc__,
-"sig=($module, data)\n"
+"a2b_uu($module, data, /)\n"
+"--\n"
+"\n"
 "Decode a line of uuencoded data.");
 
 #define BINASCII_A2B_UU_METHODDEF    \
@@ -33,7 +35,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_b2a_uu__doc__,
-"sig=($module, data)\n"
+"b2a_uu($module, data, /)\n"
+"--\n"
+"\n"
 "Uuencode line of data.");
 
 #define BINASCII_B2A_UU_METHODDEF    \
@@ -63,7 +67,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_a2b_base64__doc__,
-"sig=($module, data)\n"
+"a2b_base64($module, data, /)\n"
+"--\n"
+"\n"
 "Decode a line of base64 data.");
 
 #define BINASCII_A2B_BASE64_METHODDEF    \
@@ -93,7 +99,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_b2a_base64__doc__,
-"sig=($module, data)\n"
+"b2a_base64($module, data, /)\n"
+"--\n"
+"\n"
 "Base64-code line of data.");
 
 #define BINASCII_B2A_BASE64_METHODDEF    \
@@ -123,7 +131,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_a2b_hqx__doc__,
-"sig=($module, data)\n"
+"a2b_hqx($module, data, /)\n"
+"--\n"
+"\n"
 "Decode .hqx coding.");
 
 #define BINASCII_A2B_HQX_METHODDEF    \
@@ -153,7 +163,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_rlecode_hqx__doc__,
-"sig=($module, data)\n"
+"rlecode_hqx($module, data, /)\n"
+"--\n"
+"\n"
 "Binhex RLE-code binary data.");
 
 #define BINASCII_RLECODE_HQX_METHODDEF    \
@@ -183,7 +195,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_b2a_hqx__doc__,
-"sig=($module, data)\n"
+"b2a_hqx($module, data, /)\n"
+"--\n"
+"\n"
 "Encode .hqx data.");
 
 #define BINASCII_B2A_HQX_METHODDEF    \
@@ -213,7 +227,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_rledecode_hqx__doc__,
-"sig=($module, data)\n"
+"rledecode_hqx($module, data, /)\n"
+"--\n"
+"\n"
 "Decode hexbin RLE-coded string.");
 
 #define BINASCII_RLEDECODE_HQX_METHODDEF    \
@@ -243,7 +259,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_crc_hqx__doc__,
-"sig=($module, data, crc)\n"
+"crc_hqx($module, data, crc, /)\n"
+"--\n"
+"\n"
 "Compute hqx CRC incrementally.");
 
 #define BINASCII_CRC_HQX_METHODDEF    \
@@ -278,7 +296,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_crc32__doc__,
-"sig=($module, data, crc=0)\n"
+"crc32($module, data, crc=0, /)\n"
+"--\n"
+"\n"
 "Compute CRC-32 incrementally.");
 
 #define BINASCII_CRC32_METHODDEF    \
@@ -313,7 +333,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_b2a_hex__doc__,
-"sig=($module, data)\n"
+"b2a_hex($module, data, /)\n"
+"--\n"
+"\n"
 "Hexadecimal representation of binary data.\n"
 "\n"
 "The return value is a bytes object.  This function is also\n"
@@ -346,7 +368,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_a2b_hex__doc__,
-"sig=($module, hexstr)\n"
+"a2b_hex($module, hexstr, /)\n"
+"--\n"
+"\n"
 "Binary data of hexadecimal representation.\n"
 "\n"
 "hexstr must contain an even number of hex digits (upper or lower case).\n"
@@ -379,7 +403,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_a2b_qp__doc__,
-"sig=($module, data, header=False)\n"
+"a2b_qp($module, /, data, header=False)\n"
+"--\n"
+"\n"
 "Decode a string of qp-encoded data.");
 
 #define BINASCII_A2B_QP_METHODDEF    \
@@ -411,7 +437,9 @@ exit:
 }
 
 PyDoc_STRVAR(binascii_b2a_qp__doc__,
-"sig=($module, data, quotetabs=False, istext=True, header=False)\n"
+"b2a_qp($module, /, data, quotetabs=False, istext=True, header=False)\n"
+"--\n"
+"\n"
 "Encode a string using quoted-printable encoding.\n"
 "\n"
 "On encoding, when istext is set, newlines are not encoded, and white\n"
@@ -447,4 +475,4 @@ exit:
 
     return return_value;
 }
-/*[clinic end generated code: output=831a8ccc9f984001 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=68e2bcc6956b6213 input=a9049054013a1b77]*/
diff --git a/Modules/clinic/zlibmodule.c.h b/Modules/clinic/zlibmodule.c.h
index f810fcf81b..f54a805377 100644
--- a/Modules/clinic/zlibmodule.c.h
+++ b/Modules/clinic/zlibmodule.c.h
@@ -3,7 +3,9 @@ preserve
 [clinic start generated code]*/
 
 PyDoc_STRVAR(zlib_compress__doc__,
-"sig=($module, bytes, level=Z_DEFAULT_COMPRESSION)\n"
+"compress($module, bytes, level=Z_DEFAULT_COMPRESSION, /)\n"
+"--\n"
+"\n"
 "Returns a bytes object containing compressed data.\n"
 "\n"
 "  bytes\n"
@@ -39,7 +41,9 @@ exit:
 }
 
 PyDoc_STRVAR(zlib_decompress__doc__,
-"sig=($module, data, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)\n"
+"decompress($module, data, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE, /)\n"
+"--\n"
+"\n"
 "Returns a bytes object containing the uncompressed data.\n"
 "\n"
 "  data\n"
@@ -78,7 +82,11 @@ exit:
 }
 
 PyDoc_STRVAR(zlib_compressobj__doc__,
-"sig=($module, level=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY, zdict=None)\n"
+"compressobj($module, /, level=Z_DEFAULT_COMPRESSION, method=DEFLATED,\n"
+"            wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL,\n"
+"            strategy=Z_DEFAULT_STRATEGY, zdict=None)\n"
+"--\n"
+"\n"
 "Return a compressor object.\n"
 "\n"
 "  level\n"
@@ -132,7 +140,9 @@ exit:
 }
 
 PyDoc_STRVAR(zlib_decompressobj__doc__,
-"sig=($module, wbits=MAX_WBITS, zdict=b\'\')\n"
+"decompressobj($module, /, wbits=MAX_WBITS, zdict=b\'\')\n"
+"--\n"
+"\n"
 "Return a decompressor object.\n"
 "\n"
 "  wbits\n"
@@ -166,7 +176,9 @@ exit:
 }
 
 PyDoc_STRVAR(zlib_Compress_compress__doc__,
-"sig=($self, data)\n"
+"compress($self, data, /)\n"
+"--\n"
+"\n"
 "Returns a bytes object containing compressed data.\n"
 "\n"
 "  data\n"
@@ -203,7 +215,9 @@ exit:
 }
 
 PyDoc_STRVAR(zlib_Decompress_decompress__doc__,
-"sig=($self, data, max_length=0)\n"
+"decompress($self, data, max_length=0, /)\n"
+"--\n"
+"\n"
 "Return a bytes object containing the decompressed version of the data.\n"
 "\n"
 "  data\n"
@@ -245,7 +259,9 @@ exit:
 }
 
 PyDoc_STRVAR(zlib_Compress_flush__doc__,
-"sig=($self, mode=zlib.Z_FINISH)\n"
+"flush($self, mode=zlib.Z_FINISH, /)\n"
+"--\n"
+"\n"
 "Return a bytes object containing any remaining compressed data.\n"
 "\n"
 "  mode\n"
@@ -279,7 +295,9 @@ exit:
 #if defined(HAVE_ZLIB_COPY)
 
 PyDoc_STRVAR(zlib_Compress_copy__doc__,
-"sig=($self)\n"
+"copy($self, /)\n"
+"--\n"
+"\n"
 "Return a copy of the compression object.");
 
 #define ZLIB_COMPRESS_COPY_METHODDEF    \
@@ -303,7 +321,9 @@ zlib_Compress_copy(compobject *self, PyObject *Py_UNUSED(ignored))
 #if defined(HAVE_ZLIB_COPY)
 
 PyDoc_STRVAR(zlib_Decompress_copy__doc__,
-"sig=($self)\n"
+"copy($self, /)\n"
+"--\n"
+"\n"
 "Return a copy of the decompression object.");
 
 #define ZLIB_DECOMPRESS_COPY_METHODDEF    \
@@ -325,7 +345,9 @@ zlib_Decompress_copy(compobject *self, PyObject *Py_UNUSED(ignored))
 #endif /* !defined(ZLIB_DECOMPRESS_COPY_METHODDEF) */
 
 PyDoc_STRVAR(zlib_Decompress_flush__doc__,
-"sig=($self, length=zlib.DEF_BUF_SIZE)\n"
+"flush($self, length=zlib.DEF_BUF_SIZE, /)\n"
+"--\n"
+"\n"
 "Return a bytes object containing any remaining decompressed data.\n"
 "\n"
 "  length\n"
@@ -354,7 +376,9 @@ exit:
 }
 
 PyDoc_STRVAR(zlib_adler32__doc__,
-"sig=($module, data, value=1)\n"
+"adler32($module, data, value=1, /)\n"
+"--\n"
+"\n"
 "Compute an Adler-32 checksum of data.\n"
 "\n"
 "  value\n"
@@ -390,7 +414,9 @@ exit:
 }
 
 PyDoc_STRVAR(zlib_crc32__doc__,
-"sig=($module, data, value=0)\n"
+"crc32($module, data, value=0, /)\n"
+"--\n"
+"\n"
 "Compute a CRC-32 checksum of data.\n"
 "\n"
 "  value\n"
@@ -424,4 +450,4 @@ exit:
 
     return return_value;
 }
-/*[clinic end generated code: output=67d3e81eafcfb982 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=bc9473721ca7c962 input=a9049054013a1b77]*/