Python provides numerous places to include the documentation. The definition of a package, module, class, or function has room for a string that includes a description of the object that is being defined.
Throughout this book, we avoided showing you lengthy docstrings in each example because our focus is on the Python programming details, not the overall software product that is being delivered.
As we move beyond advanced OO design and look at the overall deliverable product, docstrings become an important part of the deliverable. Docstrings can provide us with several key pieces of information:
- The API: the parameters, return values, and exceptions raised.
- A description of what to expect.
- Optionally, the doctest test results. For more information, refer to Chapter 17, Designing for Testability.
We can, of course, write even more...
