It says "the socket() function". I think that it is better to leave references to class as a function in the context where the fact that it is a callable is more important than the fact that it is also a type. There are a lot of precedences withint(),str(),range(),map(), etc.

Would you suggest adding a.. function:: socket directive (potentially just above.. class:: socket)?

It is not needed, the role type should not affect links. For example:func:`int` and:class:`int` refer to the same.. class:: declaration. The difference is that :func: adds ().

I tried this locally (replacing all:class:`.socket` with:func:`socket`) -- the problem is that the cross-reference goes to the module object definition (library/socket.html#module-socket) rather than the socket callable.

So I think our best option is to add a.. function:: socket directive.

A

Looking further,socket() was previously documented as a function, but#23960 changed it to be documented as a class. Perhaps we could change it back?map is documented as a function, for example.