Pycharm is confused by 'type' in docstrings

[aberres]

Problem description

In quite some places the return type of functions is specified like this:

Returns
-------
swapped : type of caller (new object)

Pycharm now thinks the function returns an object of type type and warns about legitimate usage.

See #17079 for a related issue.

The problem could be mitigated by a wording avoiding any actual type as the first word.
Proposal how the change could look like: #21623