[PyKDE] signatures for qt-classes?

[Gerard Vermeulen]

On Mon, 15 Sep 2003 09:47:46 -0700
Jim Bublitz <jbublitz at nwinternet.com> wrote:

> On Monday September 15 2003 01:22, Phil Thompson wrote:
> > On Monday 15 September 2003 8:11 am, Gerard Vermeulen wrote:
[ .. ]
> > >
> > > 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.
>
Of course, I am imagining heaven, but what about appending the Python types
to the %ConvertFromTypeCode and %ConvertToTypeCode directives:

%MappedType QMap<double, QString>
{
%HeaderCode
#include <qwt_compass.h>
%End

%ConvertFromTypeCode dict
    ...
%End

%ConvertToTypeCode dict
    ...
%End
};

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

Yes, that is what I had in mind

> 
> 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.
>
What about a %DocHead directive? (to override the default doc header):

%DocHead
    someMethod(self, QString = QString.null) -> (result, errorMessage, validBool)
%End

IMO there is no need to worry too much about the data types of the objects.
Consistent/careful naming should be sufficient.
> 
> > 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.
>
I do not see this as a full documentation solution, just a way to have
succint documentation under my finger tips:
(1) readline completion: QWidget.<TAB> displays all QWidget attributes
    and methods.
(2) function signatures (try the Idle environment) display gory details like
    the order of the arguments.
> 
> 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)
> 
My idea is that a documentation string is made up of a mostly automatically
generated %DocHead and an optional %DocTail.  In my view, sip will put those
strings directly in the *.cpp files that it generates (that does not exclude
post-processing...).

Gerard