[PyKDE] signatures for qt-classes?

[Jim Bublitz]

On Monday September 15 2003 01:22, Phil Thompson wrote:
> 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"""

The only problem I'd see:

> >     """labelMap(self) -> dict"""
> >     """setLabel(self, dict)"""

This is great if sip knows that QMap => dict,  PyKDE uses 
template types that aren't in Qt (KSharedPtr stuff for example) 
and other types sip doesn't recognize that require mapped types 
(unsigned long long, long long, etc). A lot of them come from 
typedefs too, adding a level of indirection.

Right now I tag each mapped type with //converts and use that to 
do substitution when generating docs:

%MappedType KService::Ptr
//converts KService instance

Something like that, or a simple table of mapped type => string 
description, eg:

QMap => dict
QValueList => list
KService::Ptr => KService
longlong => long long

or even:

QValueList<QString> => list of QString
QMap<int,QString> => dict of int, QString

would be nice (for me, of course)

> > 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 assume that would attach to a method like %MemberCode does now?

The other problem is that for C++ like:

int someMethod (QString& data  = QString::null, QString& error,                
                          bool& ok);

I might end up with member code that in Python is:

    someMethod (data)

and returns (int, error, ok).

I currently mark this up as:

%MemberCode:
//takes data | (QString = QString.null)
//returns (int) | error | (QString) | ok | (bool)
//doc
// some comment or other if required (rarely)
//end

which is kind of ugly, but works pretty well.

> 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.

I really like the original idea and don't want to complicate it - 
just pointing out that in a small number of cases there are 
other requirements.

Personally I think a %DocTail-like solution is less of a 
maintenance headache than the %ExportedDoc stuff PyQt uses now, 
but then maybe you have a quicker way of doing that than I do.
Especially if I can put arbitrary tags in it as above (don't need 
to be tags sip recognizes - just something I can read and 
process and sip ignores)

Jim