Automatic documentation with python

A nice feature in python is the documentation strings (or docstrings) which provides a convenient way of associating documentation with Python modules, functions, classes, and methods.

An object’s docstring is defined by including a string constant as the first statement in the object’s definition.

For example:

def mean(dataPoints):
"""
This function calculates the arithmetic average of given data
"""

To get each function description you can use the associated “doc” method:

>>> print stats.mean.__doc__
>>> This function calculates the arithmetic average of given data

Do this for every function inside a module (here stats is the name of the file/module). Add arguments and return value descriptions.

You can also add a comment at the beginning of the file, to explain what it contains.

This and all functions descriptions can then be viewed with the help command: help(fileName)

>>> import stats
>>> help(stats)
Help on module stats:
NAME
stats - Basic statistics module for data analysis and inference
DESCRIPTION
This module provides functions for calculating statistics of data, including
averages, variance, and standard deviation.
FUNCTIONS 

    mean(dataPoints, precision=3)

        the arithmetic average of given data

        Arguments:

            dataPoints: a list of data points, int or float

            precision (optional): digits precision after the comma, default=3

        Returns:

            float, the mean of the input

            or StatsError if X is empty.

    

    median(dataPoints)

        the median of given data

        Arguments:

            dataPoints: a list of data points, int or float     

        Returns:

            the middle number in the sorted list, a float or an int

Advertisements