Argument Clinic docstring generator ignores a custom name for $module argument

[arhadthedev]

Input file

/*[clinic input]
my_method
    _foo: self(type="PyObject *")
    module: object
[clinic start generated code]*/

python Tools/clinic/clinic.py test.c

Current result

/*[clinic input]
preserve
[clinic start generated code]*/

PyDoc_STRVAR(my_method__doc__,
"my_method($module, /, module)\n"
"--\n"
"\n");

[snip]

my_method__doc__ continues to list renamed _foo as $module.

Expected result

-"my_method($module, /, module)\n"
+"my_method($_foo, /, module)\n"

A docstring should use an actual module/self variable name to not confuse docstring readers; its special role is denoted by $ prefix and position anyway.

This issue is a blocker for #92891 (comment).

[arhadthedev]

I localized the issue. Function format_docstring renders a docstring variable name using the following logic:

cpython/Tools/clinic/clinic.py

Lines 4975 to 4976 in 605e9c6

	name = p.converter.signature_name or p.name
	p_add(name)

For our two parameters, values are the following:

• p.converter.signature_name='module', p.name='_foo'
• p.converter.signature_name=None`, p.name='module'

In other words, the clinic seems to implicitly append ... as module to whatever we declare with self(...). And, alas, self_converter.pre_render does exactly this (line 3675):

cpython/Tools/clinic/clinic.py

Lines 3672 to 3682 in 605e9c6

	def pre_render(self):
	f = self.function
	default_type, default_name = correct_name_for_self(f)
	self.signature_name = default_name
	self.type = self.specified_type or self.type or default_type
	kind = self.function.kind
	new_or_init = kind in (METHOD_NEW, METHOD_INIT)
	if (kind == STATIC_METHOD) or new_or_init:
	self.show_in_signature = False

Is there any reason to prefer default names over the custom ones?

[arhadthedev]

Closing in favor of gh-94430 as a proper fix.