Documenting Python Code, part 1

Some of this information is borrowed from Dive Into Python, a free Python programming book for experienced programmers. Other info is from the Python Style Guide.

You can document a Python function by giving it a doc string.

def buildConnectionString(params):
"""Build a connection string from a dictionary of parameters.

Returns string."""

As noted previously, triple quotes signify a multi-line string. Everything between the start and end quotes is part of a single string, including carriage returns and other quote characters. You'll see them most often used when defining a doc string.

Everything between the triple quotes is the function's doc string, which documents what the function does. A doc string, if it exists, must be the first thing defined in a function (that is, the first thing after the colon).

You don't technically need to give your function a doc string, but you always should; the doc string is available at runtime as an attribute of the function. Many Python IDEs use the doc string to provide context-sensitive documentation, so that when you type a function name, its doc string appears as a tooltip.

From the Python Style Guide:

The doc string of a script should be usable as its "usage" message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a "-h" option, for "help"). Such a doc string should document the script's function and command line syntax, environment variables, and files. Usage messages can be fairly elaborate (several screenfuls) and should be sufficient for a new user to use the command properly, as well as a complete quick reference to all options and arguments for the sophisticated user.

There are two forms of doc strings: one-liners and multi-line doc strings. One-liners are exactly that: information that doesn't need a lot of descriptive text to explain what's going on. Triple quotes are used even though the string fits on one line to make it easy to later expand it. The closing quotes are on the same line as the opening quotes, since it looks better. There's no blank line either before or after the doc string. The doc string is a phrase ending in a period. It prescribes the function's effect as a command ("Do this", "Return that"), not as a description: e.g. don't write "Returns the pathname ..."

def kos_root():
"""Return the pathname of the KOS root directory."""
global _kos_root
if _kos_root: return _kos_root

Multi-line doc strings start out just like a single line doc string. The first line is a summary but is then followed by a blank line. After the blank line more descriptive discussion can be made. The blank line is used to seperate the summary from descriptive info for automatic indexing tools. They will use the one-line summary to create a documentation index, allowing the programmer to do less work.

When continuing your doc string after the blank line, make sure to follow the indentation rules for Python, i.e. after the blank line all of your doc string info is indented as far as the initial triple-quote.

>Part 2>