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