Documentation strings (docstrings) are considered best for larger, functional documentation, describing the use of modules, functions, classes, and methods in your code. Hash-mark comments are today best limited to smaller-scale documentation about arcane expressions or statements at strategic points on your code. This is partly because docstrings are easier to find in a source file, but also because they can be extracted and displayed by the PyDoc system.
You can see docstrings by printing an object’s __doc__ attribute, by passing it to PyDoc’s help function, and by selecting modules in PyDoc’s HTML-based user interfaces—either the -g GUI client mode in Python 3.2 and earlier, or the -b all-browser mode in Python 3.2 and later (and required as of 3.3). Both run a client/server system that displays documentation in a popped-up web browser. PyDoc can also be run to save a module’s documentation in an HTML file for later viewing or printing.
The built-in dir(X) function returns a list of all the attributes attached to any object. A list comprehension of the form [a for a in dir(X) if not a.startswith('__')] can be used to filter out internals names with underscores (we’ll learn how to wrap this in a function in the next part of the book to make it easier to use).
In Python 3.2 and earlier, you can run the PyDoc GUI interface, and select “open browser”; this opens a web page containing a link to every module available to your programs. This GUI mode no longer works as of Python 3.3. In Python 3.2 and later, you get the same functionality by running PyDoc’s newer all-browser mode with a -b command-line switch; the top-level start page displayed in a web browser in this newer mode has the same index page listing all available modules.
Mine, of course. (Seriously, there are hundreds today; the preface lists a few recommended follow-up books, both for reference and for application tutorials, and you should browse for books that fit your needs.)