Reading a reference entry

Reference documentation is dense on purpose — it's complete and precise rather than friendly. But every reference entry follows the same skeleton, so once you know the shape, the wall of text becomes a form with predictable fields. This is the doc you reach for to verify exactly how something behaves.

The standard parts

For any function or method, look for these, in this order:

• Signature — the name, its parameters, and what it returns.
• Parameters — each input: its type, whether it's required, its default.
• Return value — what comes back, and its type.
• Raises / throws — the errors it can produce, and when.
• Examples — often the fastest way in; read these first, then confirm against the prose.

Reading a signature

Signatures pack a lot into one line. Take this Python example:

str.split(sep=None, maxsplit=-1)

Decode it piece by piece:

• str.split — a method you call on a string.
• sep=None — an optional argument named sep; the =None is its default, so if you omit it, it splits on whitespace.
• maxsplit=-1 — another optional argument defaulting to -1 (meaning "no limit").

So you can call text.split() or text.split(",") or text.split(",", 2). The signature told you all three were possible without reading another word.

Read it as a contract

Put the parts together into a sentence: "I give it X and Y (Y is optional), I get back Z, and it raises E if the input is empty." That mental sentence is the whole point of a reference — it lets you use something correctly without reading its source.

Where to go next

Sometimes the answer isn't in a web page at all — it's a command away. Next: finding answers yourself with --help, man, and built-in help.