# Dive Into Python

Python from novice to pro

Find:

## 2.3. Documenting Functions

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

### Example 2.2. Defining the `buildConnectionString` Function's `doc string`

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

        Returns string."""

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 can use them anywhere, but you'll see them most often used when defining a `doc string`.

Triple quotes are also an easy way to define a string with both single and double quotes, like `qq/.../` in Perl.

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. I know you've heard this in every programming class you've ever taken, but Python gives you an added incentive: 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. This can be incredibly helpful, but it's only as good as the `doc string`s you write.

### Further Reading on Documenting Functions

- PEP 257 defines `doc string` conventions.
- Python Style Guide discusses how to write a good `doc string`.
- Python Tutorial discusses conventions for spacing in `doc string`s.