Doc strings

The following are relax's conventions for docstrings. Many of these are Python conventions.

• The standard Python convention of a one line description separated from a detailed description by an empty line should be adhered to. This line must start with a capital letter and end in a period. This convention is required for certain docstring parsers (see the Python docs).
• All functions should have a docstring describing in detail the function, structure, and organisation of the code.
• A docstring should be followed by an empty line.
• Indentation of the docstring should be the same as that of the first line of code, excluding indented lists, etc.

An example of a single line docstring is:

    def delete(self):
        """Function for deleting all model-free data."""

An example of a multiline docstring is:

def aic(chi2, k, n):
    """Akaike's Information Criteria (AIC).

    The formula is::

        AIC = chi2 + 2k


    @param chi2:    The minimised chi-squared value.
    @type chi2:     float
    @param k:       The number of parameters in the model.
    @type k:        int
    @param n:       The dimension of the relaxation data set.
    @type n:        int
    @return:        The AIC value.
    @rtype:         float
    """

    return chi2 + 2.0*k

In addition to the text descriptions, the docstrings use the Epydoc markup language to describe arguments, return values, and other information about the code. See http://epydoc.sourceforge.net/fields.html for a listing of all the epydoc fields allowed. This markup language is important for the creation of the API documentation and to help developers understand the purpose and operation of the code.