Writing file-level docstrings, including modules and packages
A package or a module's purpose is to contain a number of elements. A package contains modules as well as classes, global variables, and functions. A module contains classes, global variables, and functions. The top-level docstrings on these containers can act as road-maps to explain the general features of the package or module. The details are delegated to the individual classes or functions.
We might have a module docstring that looks like the following code:
Blackjack Cards and Decks ========================= This module contains a definition of ``Card``, ``Deck`` and ``Shoe`` suitable for Blackjack. The ``Card`` class hierarchy ----------------------------- The ``Card`` class hierarchy includes the following class definitions. ``Card`` is the superclass as well as being the class for number cards. ``FaceCard`` defines face cards: J, Q and K. ``AceCard`` defines the Ace. This is special in Blackjack because it creates a...
