2.4 Documentation Strings

Every function should have a docstring that includes the following information: Use the following template when documenting functions. Note the indentation:
def point(self, x=1, y=2):
    r"""           # note the r for "raw string"
    This function returns the point $(x^5,y)$.

    INPUT:
        self -- anything special about self
        x -- integer (default: 1) the ...
        y -- integer (default: 2) the ...

    OUTPUT:
        integer -- the ...

    EXAMPLES:
    This example illustrates ...
        sage: A = ModuliSpace()
        sage: A.point(2,3)
        xxx

    We now ...
        sage: B = A.point(5,6)
        sage: xxx

    It is an error to ...
        sage: C = A.point('x',7)
        Traceback (most recent call last):
        ...
        TypeError: unable to convert x (=r) to an integer

    NOTES:
        This function uses the algorithm of [BCDT] to determine whether
        an elliptic curve E over Q is modular.

        ...

        REFERENCES:
             [BCDT] Breuil, Conrad, Diamond, Taylor, "Modularity ...."

    AUTHORS: 
        - William Stein (2005-01-03)
        - First_name Last_name (yyyy-mm-dd)
    """
    <body of the function>
You are strongly encouraged to:

The code in the examples should pass automatic testing. This means that if the above code is in the file f.py (or f.sage), then sage -t f.py should not give any error messages. Testing occurs with full Sage preparsing of input within the standard Sage shell environment. Important. The file f.py is not imported when running tests unless you have arranged that it be imported into your Sage environment, i.e., unless its functions are available when you start Sage using the sage command.



Subsections
See About this document... for information on suggesting changes.