[PyKDE] signatures for qt-classes?

[Jim Bublitz]

On Monday September 15 2003 11:01, Gerard Vermeulen wrote:
> 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:

> 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
> };

If we're imagining heaven, 'dict' could be a type or an arbitrary 
string (of reasonably short length)

> What about a %DocHead directive? (to override the default doc
> header):

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

Yes - that would work for me (assuming I can stick the variable 
names in there too - I have those available with my present 
scheme).  

> IMO there is no need to worry too much about the data types of
> the objects. Consistent/careful naming should be sufficient.

Agree - it should be readable not necessarily compilable (so a 
data type of "Python list of int" should be allowable). 

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

Right - which is why I wouldn't want to complicate it more than 
what's required for those.  It should cover all cases though,
even if it ends up returning "see full docs" for some 
particularly obnoxious case. It shouldn't return incorrect info.

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

Most projects would need very little of the optional %DocTail 
stuff too. 

I do the markup inside specially tagged comments right now (a 
little dangerous, but hasn't been a problem yet), so anything 
along these lines would be somewhere between neutral and an 
improvement for me.


Jim