Passing objects to a function

[Andrew Bennetts]

On Sun, May 09, 2004 at 04:36:53PM -0700, Robert Brewer wrote:
> 
> Barring that, however, the right way to document a function is: the
> documentation string, of course!
> 
[...]
> 
> ...following the example for the 'str' builtin, you might write:
> 
> def BlackJackValue(hand):
>     """BlackJackValue(Hand_instance) -> int\n\nReturn an integer, which
> is the value of the Hand according to the rules of BlackJack."""
>     pass

Except I hope you'd use real newlines, rather than \n, for the sake of
people trying to read the source.

If you used epydoc <http://epydoc.sf.net/>, you could specify types like
this:

def BlackJackValue(hand):
    """Return the value of the hand, according to the rules of Blackjack.

    @arg hand: The hand to calculate the value of.
    @type hand: Hand

    @returns: The value of the hand
    @rtype: int
    """

It's reasonably readable, if somewhat verbose.  And then epydoc can make
reasonably nice HTML API docs for you, if you're into that sort of thing :)

-Andrew.