[PyKDE] signatures for qt-classes?

[Phil Thompson]

On Monday 15 September 2003 8:11 am, Gerard Vermeulen wrote:
> On Sun, 14 Sep 2003 12:57:08 -0400
>
> Gordon Tyler <gordon at doxxx.net> wrote:
> > Phil Thompson wrote:
> > > On Sunday 14 September 2003 10:51 am, holger krekel wrote:
> > >>However, i am missing two things, mainly docstrings and
> > >>signature information.  While i can imagine that providing
> > >>docstrings is a major task i wonder if it's possible to
> > >>maintain a more telling signature than '*args'.  I really like
> > >>to learn libraries from the cmdline (with rlcompleter2-completion)
> > >>and i think i am not alone.
> > >>
> > >>Or is this "uncurable" with current binding-technologies?
> > >
> > > rlcompleter works fine with PyQt as far as I know.
> >
> > I think the problem is more that there are no docstrings in the PyQt
> > bindings. I was actually wondering myself whether it would be possible
> > to automatically generate docstrings based on the docs in the C++
> > comments?
>
> Or generate part of the doc-strings automatically, for instance
>
> >>> print filter.__doc__
>
> filter(function or None, sequence) -> list, tuple, or string
>
> Return those items of sequence for which function(item) is true.  If
> function is None, return the items that are true.  If sequence is a tuple
> or string, return the same type, else return a list.
>
>
> here the first line is used by Idle as a tooltip hint (this is a feature
> which seems to be missing from Eric-3.2).
>
> Such first lines could be automatically generated by sip; so a class
> declaration
>
> class QwtCompass: QwtDial
> {
>     QwtCompass(QWidget * /TransferThis/ = 0, const char * = 0);
>     void setRose(QwtCompassRose * /Transfer/);
>     QwtCompassRose *rose();
>     QMap<double, QString> &labelMap();
>     void setLabelMap(const QMap<double, QString> &);
> }
>
> would give the doc-strings:
>     """__init__(self[, QWidget[, string]])"""
>     """setRose(self, QwtCompassRose)"""
>     """rose(self) -> QwtCompaseRose"""
>     """labelMap(self) -> dict"""
>     """setLabel(self, dict)"""
>
> Of course there remains the problem of calls with more than 1 function
> signature.
>
> This could be supplemented with a directive
>
> %DocTail
> Return those items of sequence for which function(item) is true.  If
> function is None, return the items that are true.  If sequence is a tuple
> or string, return the same type, else return a list.
> %End
>
> to supplement the documentation for the really courageous (or crazy)
> library wrappers.

I think this is a good idea and shouldn't be too difficult. Multiple 
signatures would be handled by just listing them one after another. PyQt 
wouldn't include any use of %DocTail - too much of a maintenance problem.

Phil