InterfaceMarkup

The interface to any new or modified routine in fparser must be fully documented using Sphinx mark-up. An example of how to do this is shown below:

def parse(alg_filename, api="", invoke_name="invoke", inf_name="inf",
          kernel_path="", line_length=False):
    '''
    Takes a GungHo algorithm specification as input and outputs an AST of
    this specification and an object containing information about the
    invocation calls in the algorithm specification and any associated kernel
    implementations.

    :param str alg_filename: the file containing the algorithm specification.
    :param str invoke_name: the expected name of the invocation calls in the \
        algorithm specification.
    :param str inf_name: the expected module name of any required \
        infrastructure routines.
    :param str kernel_path: the path to search for kernel source files (if \
        different from the location of the algorithm source).
    :param line_length: a logical flag specifying whether we care about line \
        lengths being longer.
    :type line_length: bool

    :return: 2-tuple containing the top-level node in the AST and an object \
        describing all of the invoke()'s found in the Algorithm file.
    :rtype: (:py:class:`psyclone.psyGen.SubroutineGen`, :py:class:`psyclone.parser.Invokes`)

    :raises IOError: if the filename or search path does not exist.
    :raises ParseError: if there is an error in the parsing.
    :raises RuntimeError: if there is an error in the parsing.

    '''

Note:

1. each different exception that the routine can raise is documented separately;
2. if an argument type is a Python built-in (e.g. str, int or bool) then the type can be specified in-line with the argument description. However, if it is of a derived type then, for clarity, it should be specified in a separate :type my_arg: line.
3. the separation of input arguments, return values and exceptions.
4. the blank line before the end quotes.
5. the "" when there are multiple lines and the indentation of text on subsequent lines. The example shows an indentation of 4 but indentation to the start of the text on the previous line is also acceptable.
6. that description text starts with a lower case word and finishes with a full stop.