RFC: docstring type names in Phoenix

Hi all,

I'm looking for some opinions or suggestions on an aspect of Phoenix that I'm working on at the moment. Namely, should the automatically generated docstrings show the parameter types or just the parameter names and default values (if any).

For example, without parameter types:
"""
SetSize(x, y, width, height, sizeFlags=SIZE_AUTO)
SetSize(rect)
SetSize(size)
SetSize(width, height)

Sets the size of the window in pixels.
"""

With parameter types, using a C-like syntax:
"""
SetSize(int x, int y, int width, int height, int sizeFlags=SIZE_AUTO)
SetSize(Rect rect)
SetSize(Size size)
SetSize(int width, int height)

Sets the size of the window in pixels.
"""

Or perhaps there is some other syntax that would be better for Python code?

Keep in mind that this is just for the docstrings which are going to be intentionally kept brief. The main docs generator will have access to more detailed descriptions (if they are specified in the interface headers) and also the full information about the parameter types and etc., and will have the room to be however as verbose about it as we decide is necessary.

P.S. If the functions return a value then the docstrings will have a " -> TypeName" on the end of the function signature lines.

···

--
Robin Dunn
Software Craftsman
http://wxPython.org

Hi Robin,

Hi all,

I'm looking for some opinions or suggestions on an aspect of Phoenix that I'm working on at the moment. Namely, should the automatically generated docstrings show the parameter types or just the parameter names and default values (if any).

For example, without parameter types:
"""
SetSize(x, y, width, height, sizeFlags=SIZE_AUTO)
SetSize(rect)
SetSize(size)
SetSize(width, height)

Sets the size of the window in pixels.
"""

With parameter types, using a C-like syntax:
"""
SetSize(int x, int y, int width, int height, int sizeFlags=SIZE_AUTO)
SetSize(Rect rect)
SetSize(Size size)
SetSize(int width, int height)

Sets the size of the window in pixels.
"""

Or perhaps there is some other syntax that would be better for Python code?

I'd suggest without parameter types, to be consistent with the Python docs, and also because in many cases, there isn't a single acceptable type for a given parameter thanks to duck typing and the C++ type mapping.

Thanks,

Kevin

···

On Sep 15, 2011, at 8:16 PM, Robin Dunn wrote:

Keep in mind that this is just for the docstrings which are going to be intentionally kept brief. The main docs generator will have access to more detailed descriptions (if they are specified in the interface headers) and also the full information about the parameter types and etc., and will have the room to be however as verbose about it as we decide is necessary.

P.S. If the functions return a value then the docstrings will have a " -> TypeName" on the end of the function signature lines.

--
Robin Dunn
Software Craftsman
http://wxPython.org

--
To unsubscribe, send email to wxPython-dev+unsubscribe@googlegroups.com
or visit http://groups.google.com/group/wxPython-dev?hl=en

Hi All,

Hi Robin,

Hi all,

I’m looking for some opinions or suggestions on an aspect of Phoenix that I’m working on at the moment. Namely, should the automatically generated docstrings show the parameter types or just the parameter names and default values (if any).

For example, without parameter types:

“”"

SetSize(x, y, width, height, sizeFlags=SIZE_AUTO)

SetSize(rect)

SetSize(size)

SetSize(width, height)

Sets the size of the window in pixels.

“”"

With parameter types, using a C-like syntax:

“”"

SetSize(int x, int y, int width, int height, int sizeFlags=SIZE_AUTO)

SetSize(Rect rect)

SetSize(Size size)

SetSize(int width, int height)

Sets the size of the window in pixels.

“”"

Or perhaps there is some other syntax that would be better for Python code?

I’d suggest without parameter types, to be consistent with the Python docs, and also because in many cases, there isn’t a single acceptable type for a given parameter thanks to duck typing and the C++ type mapping.

I agree with Kevin. However, if and when we switch to Sphinx for the documentation, there might be an elegant way to include the parameter type into the docs in this way

def SetSize(x, y, width, height, sizeFlags=SIZE_AUTO):

“”"

Sets the size of the window in pixels.

:param x: the window width, in pixels

:type x: int

“”"

Etcetera. This will give this kind of results:

http://sphinx.pocoo.org/domains.html#info-field-lists

I am currenly implementing it for AGW as well.

Andrea.

“Imagination Is The Only Weapon In The War Against Reality.”
http://xoomer.alice.it/infinity77/

import PyQt4.QtGui

Traceback (most recent call last):

File “”, line 1, in

ImportError: No module named PyQt4.QtGui

import pygtk

Traceback (most recent call last):

File “”, line 1, in

ImportError: No module named pygtk

···

On 16 September 2011 06:16, Kevin Ollivier wrote:

On Sep 15, 2011, at 8:16 PM, Robin Dunn wrote:

import wx

I remembered that Python 3 introduced “Function annotations”: http://www.python.org/dev/peps/pep-3107 exactly for this kind of usage.

Then I did a quick search on Google Code Search, and I found a project which already uses this syntax in their docstrings!

See for example:

http://www.google.com/codesearch#pjoUodY8a2g/gui/common_widgets.py&type=cs&l=252

and all other files of this project! It even has guidelines:

http://www.google.com/codesearch#pjoUodY8a2g/doc/coding_conventions.txt&type=cs&l=97

I would change it a little though, for example IMO it’s not necessary to document that a constructor returns an instance of the class…

···

2011/9/16 Robin Dunn robin@alldunn.com

Hi all,

I’m looking for some opinions or suggestions on an aspect of Phoenix that I’m working on at the moment. Namely, should the automatically generated docstrings show the parameter types or just the parameter names and default values (if any).

For example, without parameter types:

“”"

SetSize(x, y, width, height, sizeFlags=SIZE_AUTO)

SetSize(rect)

SetSize(size)

SetSize(width, height)

Sets the size of the window in pixels.

“”"

With parameter types, using a C-like syntax:

“”"

SetSize(int x, int y, int width, int height, int sizeFlags=SIZE_AUTO)

SetSize(Rect rect)

SetSize(Size size)

SetSize(int width, int height)

Sets the size of the window in pixels.

“”"

Or perhaps there is some other syntax that would be better for Python code?


Amaury Forgeot d’Arc

+1

pep-3107 is the example to follow IMHO.
···

-- Regards
David Hughes
Forestfield Software

That's the way I've been leaning too.

···

On 9/15/11 9:16 PM, Kevin Ollivier wrote:

I'd suggest without parameter types, to be consistent with the Python
docs, and also because in many cases, there isn't a single acceptable
type for a given parameter thanks to duck typing and the C++ type
mapping.

--
Robin Dunn
Software Craftsman

Thanks, I knew there was something like that, but I didn't have the correct google search terms. The idea and basic syntax has been around since Python 2.0 IIRC, as there was a SIG that was investigating adding optional type checking to the language, but it fizzled out.

···

On 9/15/11 11:55 PM, Amaury Forgeot d'Arc wrote:

I remembered that Python 3 introduced "Function annotations":
PEP 3107 – Function Annotations | peps.python.org exactly for this kind of usage.

--
Robin Dunn
Software Craftsman

Oops, I sent before I finished my thought: The reason I like the arg-name-only approach is because it makes the docstrings simple and a lot less cluttered looking than if the type info is there too, and more likely to fit in a smallish tooltip-like window that may be shown by an IDE or what-not. If the programmer needs more information then they can go to the online docs or help file.

Very detailed docstrings are great when the programmer is expected to be reading the Python code, but most of the docstrings for the core Phoenix modules will not be in Python code, but in the C++ code for the extension modules.

···

On 9/16/11 1:15 AM, Robin Dunn wrote:

On 9/15/11 9:16 PM, Kevin Ollivier wrote:

I'd suggest without parameter types, to be consistent with the Python
docs, and also because in many cases, there isn't a single acceptable
type for a given parameter thanks to duck typing and the C++ type
mapping.

That's the way I've been leaning too.

--
Robin Dunn
Software Craftsman

Hi All,

Hi Robin,

        > Hi all,

        >

        > I'm looking for some opinions or suggestions on an

aspect of Phoenix that I’m working on at the moment.
Namely, should the automatically generated docstrings show
the parameter types or just the parameter names and default
values (if any).

        >

        > For example, without parameter types:

        > """

        > SetSize(x, y, width, height, sizeFlags=SIZE_AUTO)

        > SetSize(rect)

        > SetSize(size)

        > SetSize(width, height)

        >

        > Sets the size of the window in pixels.

        > """

        >

        > With parameter types, using a C-like syntax:

        > """

        > SetSize(int x, int y, int width, int height, int

sizeFlags=SIZE_AUTO)

        > SetSize(Rect rect)

        > SetSize(Size size)

        > SetSize(int width, int height)

        >

        > Sets the size of the window in pixels.

        > """

        >

        > Or perhaps there is some other syntax that would be

better for Python code?

      I'd suggest without parameter types, to be consistent with the

Python docs, and also because in many cases, there isn’t a
single acceptable type for a given parameter thanks to duck
typing and the C++ type mapping.

I agree with Kevin.

+1, short is great.  In my view this is just a remember, if one

needs more details then there is the doc and if the new doc does
something along the lines suggested below then that is great.

    However, if and when we switch to Sphinx for the

documentation, there might be an elegant way to include the
parameter type into the docs in this way

def SetSize(x, y, width, height, sizeFlags=SIZE_AUTO):

“”"

Sets the size of the window in pixels.

:param x: the window width, in pixels

:type x: int

“”"

+1

Etcetera. This will give this kind of results:

http://sphinx.pocoo.org/domains.html#info-field-lists

I am currenly implementing it for AGW as well.

Is this someone you could use help or are you doing it with some

script?

Robin I hope you speak up when it is time that people like me could

help out on things - testing and maybe simple code changes in wx.lib
unless it is all done with scripts.

Werner
···

On 09/16/2011 08:31 AM, Andrea Gavana wrote:

    On 16 September 2011 06:16, Kevin > Ollivier wrote:
        On Sep 15, 2011, at 8:16 PM, Robin Dunn wrote:

I will. There are still a few foundation things I need to make decisions on and get implemented, and also getting more of the C++ classes wrapped, before I'm comfortable to really open things up. But that day is coming. I expect that wx.lib and PyCrust will be good places for people to get involved. Other things that come to mind are things like expanding the unittests, identifying places in the docs that are too C++-ish and should be python-ized, etc.

···

On 9/16/11 3:20 AM, werner wrote:

Robin I hope you speak up when it is time that people like me could help
out on things - testing and maybe simple code changes in wx.lib unless
it is all done with scripts.

--
Robin Dunn
Software Craftsman

I'd suggest without parameter types, to be consistent with the Python
docs, and also because in many cases, there isn't a single acceptable
type for a given parameter thanks to duck typing and the C++ type
mapping.

True, and it's really ugly right in there with the function signature like C.

arg-name-only approach is because it makes the docstrings simple and a
lot less cluttered looking than if the type info is there too, and more
likely to fit in a smallish tooltip-like window that may be shown by an
IDE or what-not.

I like that first line being really simple, but as a heavy user of ipython's "?" (that's a what-not, yes?), I really like having what I need to know in a docstring, so:

···

On 9/16/11 1:21 AM, Robin Dunn wrote:

On 9/15/11 11:31 PM, Andrea Gavana wrote:

I agree with Kevin. However, if and when we switch to Sphinx for the
documentation, there might be an elegant way to include the parameter
type into the docs in this way

def SetSize(x, y, width, height, sizeFlags=SIZE_AUTO):
"""
     Sets the size of the window in pixels.

     :param `x`: the window width, in pixels
     :type `x`: int
"""

+1

-Chris

--
Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov