Including descriptions and documentation

When we have a useful script, we often need to leave notes for ourselves—and others—on what it does, how it solves some particular problem, and when it should be used.

Because clarity is important, there are some formatting recipes that can help make the documentation very clear. This recipe also contains a suggested outline so that the documentation will be reasonably complete.

Getting ready

If we've used the Writing python script and module files - syntax basics recipe to build a script file, we'll have put a small documentation string in our script file. We'll expand on this documentation string.

There are other places where documentation strings should be used. We'll look that these additional locations in Chapter 3, Function Definitions, and Chapter 6, Basics of Classes and Objects.

We have two general kinds of modules for which we'll be writing summary docstrings:

• Library Modules: These files will contain mostly function definitions as well as class...