Houston, we have docstrings!!!

wxPython Dev
1

Robin Dunn wrote:

Kevin Ollivier wrote:

I also vote for docs with the types included. =)

I think I am leaning the other way. Yes the extra info is great, but
think about it from the perspective of somebody who hasn't been using
the existing wx docs for a long time and only knows Python. Would
types in the declaration cause more confusion than it solves? Would a
different syntax help? Boa uses something that looks like Pascal,
with the types after the names, but that looks even stranger to me...

Hmmm.. After thinking about this for a few minutes, the following
occurs to me: whatever else it is, wxPython is still mostly a wrapper
around C++ classes, and therefore it's critical that the types be right,
or the code simply will not work. I therefore think that it's more
helpful if their doc, in some form, reflect the expected types.

Also, I, for one, as a true Python zealot, still occasionally find
the lack of expected type information for functions' documentation
to be annoying, and the regular python help usually then has to go
into prose to describe the expected types anyway. So I say,
leave 'em in.

The only hesitancy I have is that the types "wxWindow", "wxPoint,"
etc. are not regular python types; where will people go to find out
what these mean? (What would be *really* slick is to somehow make
the non-builtin type labels hyperlinks to doc strings that define
them-- But I suppose that's for another day. :slight_smile:
Btw, if you leave 'em in, wouldn't these be wx.Window and wx.Point? :wink:

My $0.02,
/W

···

--
Will Sadkin
Parlance Corporation
www.nameconnector.com

2

Will Sadkin <wsadkin@nameconnector.com> writes:

Robin Dunn wrote:
> Kevin Ollivier wrote:
>> I also vote for docs with the types included. =)
>
> I think I am leaning the other way. Yes the extra info is great,
> but think about it from the perspective of somebody who hasn't
> been using the existing wx docs for a long time and only knows
> Python. Would types in the declaration cause more confusion than
> it solves? Would a different syntax help? Boa uses something
> that looks like Pascal, with the types after the names, but that
> looks even stranger to me...

Hmmm.. After thinking about this for a few minutes, the following
occurs to me: whatever else it is, wxPython is still mostly a
wrapper around C++ classes, and therefore it's critical that the
types be right, or the code simply will not work. I therefore think
that it's more helpful if their doc, in some form, reflect the
expected types.

Also, I, for one, as a true Python zealot, still occasionally find
the lack of expected type information for functions' documentation
to be annoying, and the regular python help usually then has to go
into prose to describe the expected types anyway. So I say, leave
'em in.

You make some very good points, Will. It would be nice to know if any
other users of SWIG have settled on a convention when wrapping C and
C++ code. Or are we breaking new ground here?

I'm still not convinced I want to see type info in the arg spec, but
I think we should collect as much evidence for both sides of the issue
so that at least Robin is making an informed decision.

One question I have is how to handle parameters that can be of more
than one type. Can't you pass an (x, y) tuple in most places where a
wx.Point is expected, for example? Isn't that easier and more
Pythonic in all use cases where you don't already have a wx.Point
object? How do we convey that in the docstrings?

···

--
Patrick K. O'Brien
Orbtech http://www.orbtech.com/web/pobrien
-----------------------------------------------
"Your source for Python programming expertise."
-----------------------------------------------

3

Robin Dunn wrote:

Kevin Ollivier wrote:

I also vote for docs with the types included. =)

I think I am leaning the other way. Yes the extra info is great, but
think about it from the perspective of somebody who hasn't been using
the existing wx docs for a long time and only knows Python. Would
types in the declaration cause more confusion than it solves? Would a
different syntax help? Boa uses something that looks like Pascal,
with the types after the names, but that looks even stranger to me...

Hmmm.. After thinking about this for a few minutes, the following
occurs to me: whatever else it is, wxPython is still mostly a wrapper
around C++ classes, and therefore it's critical that the types be right,
or the code simply will not work. I therefore think that it's more
helpful if their doc, in some form, reflect the expected types.

Also, I, for one, as a true Python zealot, still occasionally find
the lack of expected type information for functions' documentation
to be annoying, and the regular python help usually then has to go
into prose to describe the expected types anyway. So I say,
leave 'em in.

This was my perspective too. I originally thought 'no types!' because of my Python background, then I thought - what's to tell someone they can't pass a PIL bitmap into a wxBitmapButton or wxImageList, for example? Someone who thought the module was written in Python might assume you could do just that. I'm sure if folks wanted to go through the classes, they'd find other examples like this. Since wxPython is wxWindows at the core, it will probably never 100% work like a Python module and always except Python data for everything. Sometimes the types do matter, and not having them is more confusing than having them, IMHO. (Even people in Python are used to arguments having some sort of 'type', they just aren't used to having to care what that type is.)

I guess if we documented each argument and listed the allowed types, that would work for me too, as long as it was displayed prominently in some way.

The only hesitancy I have is that the types "wxWindow", "wxPoint,"
etc. are not regular python types; where will people go to find out
what these mean? (What would be *really* slick is to somehow make
the non-builtin type labels hyperlinks to doc strings that define
them-- But I suppose that's for another day. :slight_smile:
Btw, if you leave 'em in, wouldn't these be wx.Window and wx.Point? :wink:

All the classes should still be accessible, so the docs can be linked or at the very least I imagine they could review an alphabetical class list like the wxWindows docs. It wouldn't be hard to do an automated keyword search with automated expressions. So long as every instance of wx.Point was written as such (or at least Point with a capital P) it wouldn't be hard to search through the docs and auto-generate links.

Thanks,

Kevin

···

On Nov 14, 2003, at 5:01 AM, Will Sadkin wrote:

4

Patrick K. O'Brien wrote:

You make some very good points, Will. It would be nice to know if any
other users of SWIG have settled on a convention when wrapping C and
C++ code. Or are we breaking new ground here?

For SWIG and docstrings we are. The old SWIG had the ability to generate (very limited) ascii or html docs and IIRC it did specify param types. I think it just copied the C declaration of the parameters.

The builtin Python extensions that I've looked at so far that have docstrings (like _socket for example) do not specify param types.

I'm still not convinced I want to see type info in the arg spec, but
I think we should collect as much evidence for both sides of the issue
so that at least Robin is making an informed decision.

Thanks.

One question I have is how to handle parameters that can be of more
than one type. Can't you pass an (x, y) tuple in most places where a
wx.Point is expected, for example?

s/most places/every place/

SWIG's typemaps make it automatic and global.

Isn't that easier and more
Pythonic in all use cases where you don't already have a wx.Point
object? How do we convey that in the docstrings?

I don't think we can, not automatically at least, (unless you can parse the code in the typemaps and deduce how it is converting things. <wink> ) OTOH, the docstring for Point can say that it can normally be replaced by a (x,y) tuple.

···

--
Robin Dunn
Software Craftsman
http://wxPython.org Java give you jitters? Relax with wxPython!