2.4 Documentation Strings

Every

A one-sentence description of the function, followed by a blank line.

An INPUT and an OUTPUT block for input and output arguments (see below for format). The type names should be descriptive, but do not have to represent the exact Sage/Python types. For example, use ``integer'' for anything that behaves like an integer; you do not have to put a precise type name such as int.

An EXAMPLES block for examples. This is not optional.

A NOTES block for special notes (optional). Include information such as algorithm used, references, etc.

An AUTHORS block (important!).

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>

strongly encouraged

Use nice LaTeX formating everywhere but in the INPUT/OUTPUT blocks.

Liberally describe what the examples do. Note that there must be a blank line after the example code and before the explanatory text for the next example (indentation isn't enough).

Illustrate any exceptions raised by the function with examples, as given above (It is an error to ...; In particular, use ...).

Include many examples. These are automatically tested on a regular basis, and are crucial for the quality and adaptability of Sage. Without such examples, small changes to one part of Sage that break something else might not go seen until much later when someone uses the system, which is frustrating.

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.

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