[PyQt] About the automatically generated docstrings

[Elvis Stansvik]

Hi all,

I'm following this PyCharm bug:

    https://youtrack.jetbrains.com/issue/PY-16818

The problem is that PyCharm is misparsing the automatically generated
docstrings present in PyQt5 when it generates the stubs it uses for
syntax checking, autocompletion et.c., which leads to false negatives
in the checking and less than stellar autocompletion.

Looking at the stub generation output (which includes the original
docstring from the PyQt5 library), one can see that PyQt5 is using a
format for the docstrings that is slightly unorthodox:

Example from the stub for QAbstractItemModel:

def columnsMoved(self, *args, **kwargs): # real signature unknown
    """ QAbstractItemModel.columnsMoved[QModelIndex, int, int,
QModelIndex, int] [signal] """
    pass

Here the docstring is using brackets ([ and ]) instead of parenthesis
around the method signature.

And also:

def headerData(self, p_int, Qt_Orientation, int_role=None): # real
signature unknown; restored from __doc__
    """ QAbstractItemModel.headerData(int, Qt.Orientation, int
role=Qt.DisplayRole) -> QVariant """
    return QVariant

Here, for the first two parameters, the parameter name is missing. And
PyCharm is also struggling to parse the "<type> <name>=<default>"
convention that PyQt5 uses for the third argument.

My question is whether these formats that PyQt5 uses is used by other
tools? If so, I guess it's out of the question to change it into
something that PyCharm has an easier time parsing? If not, then maybe
PyQt5 and PyCharm could meet halfway so to speak: PyQt5 could change
some of the stranger formats it uses, such as the brackets around the
signature of signals (is that a bug?) and missing parameter names, and
PyCharm could improve its parsing algorithms to special-handle the
other conventions that PyQt5 uses?

Cheers,
Elvis