python-docstring.md

Com documentar funcions i com aprofitar-ho amb ipython notebook

Com documentar funcions:

Python permet documentar funcions amb docstrings. Un docstring és una cadena de text que va just després de la definició de la funció i que descriu què fa la funció, quins arguments necessita i què retorna per pantalla.

def digueshola():
    """ Aquesta funció imprimeix hola per pantalla."""
    print "hola"

Com demanar ajuda a l'ipython notebook

Tots els programadors de python utilitzem aquest conveni, tant és així que l'ipython extreu els docstrings de les funcions per ajudar-te a programar.

Si en el propi ipython has executat import turtle i a continuació fas turtle.circle( i apretes la tecla tabulador, l'ipython et mostrarà el docstring de la funció turtle.circle:

Draw a circle with given radius.

Arguments:
radius -- a number
extent (optional) -- a number
steps (optional) -- an integer

Draw a circle with given radius. The center is radius units left
of the turtle; extent - an angle - determines which part of the
circle is drawn. If extent is not given, draw the entire circle.
If extent is not a full circle, one endpoint of the arc is the
current pen position. Draw the arc in counterclockwise direction
if radius is positive, otherwise in clockwise direction. Finally
the direction of the turtle is changed by the amount of extent.

As the circle is approximated by an inscribed regular polygon,
steps determines the number of steps to use. If not given,
it will be calculated automatically. Maybe used to draw regular
polygons.

call: circle(radius)                  # full circle
--or: circle(radius, extent)          # arc
--or: circle(radius, extent, steps)
--or: circle(radius, steps=6)         # 6-sided polygon

Example:
>>> circle(50)
>>> circle(120, 180)  # semicircle

És molt important que la comanda import turtle s'hagi executat abans, per exemple havent-la posat en una cel·la anterior.