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.""" 
  1. 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 ...

Get Modern Python Cookbook now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.