[Tutor] Re: Returned values

[Michael Janssen]

On Fri, 19 Dec 2003, Ryan Sheehy wrote:

> I have done some basic programming in a software package where the help
> files contained info for a function and would be written as such:
>
> xyz(whatever_variable: integer); boolean
>
> ... where the 'whatever_variable' would need to be an integer and the
> function 'xyz' would return a boolean result. And I thought this would be
> the norm with any programming language! :o)
>
> I couldn't see these features in Python help files and was wondering how I
> would know what the result would be.

indeed the python documentation doesn't do much formal description (but
should say in plain text what happens).

When you want to get a description like "xyz(whatever_variable:
integer); boolean" you must use the online help. For example:
"help(int)" enters help-mode and shows the definition of the int-class
(one might expect it shows the definition of the int *function* but int
acts both as class and function (it's a special case)). Now the
relevant output:

"""
Help on class int in module __builtin__:

class int(object)
 |  int(x[, base]) -> integer
"""

---> voila!


This online help is generated from docstrings (compare
http://www.python.org/doc/essays/styleguide.html for docstrings). Since
they are written within code they are more out of the view of a
programmer.


In case even the docstring doesn't reveal the type of the return value,
you will take a look at the source and try to figure out, what it might
return (this might be called "documentation by good-to-read syntax" ;-)


Michael