Modern Python Cookbook

How to do it...

We'll generally write the following things for a function description:

• Synopsis
• Description
• Parameters
• Returns
• Exceptions
• Test cases
• Anything else that seems meaningful

Here's how we'll create nice documentation for a function. We can apply a similar recipe for a function, or even a module:

1. Write the synopsis: A proper subject isn't required—we don't write This function computes...; we start with Computes.... There's no reason to overstate the context:

        def Twc(T, V): 
            """Computes the wind chill temperature.""" 

2. Write the description with details:

        def Twc(T, V): 
            """Computes the wind chill temperature 
 
            The wind-chill, :math:`T_{wc}`, is based on 
            air temperature, T, and wind speed, V. 
            """ 

In this case, we used a little ...