Documentation

Dive into Deep Learning · §1.7

Using an unfamiliar API
discover · inspect · read · verify.

A procedure for consulting an API

Motivation

No book covers an entire framework, and libraries change across releases. Four steps answer most routine questions from within a notebook: discover available names, inspect the interface, read the documentation, and verify the behavior with a small example.

Use the official reference and tutorial pages for the supported interface.

Figuring out an unfamiliar API: a repeatable loopDiscoverdir() · TabInspecthelp() · ?Readdocs · source ??Verifyrun a quick teststill stuck? refine the query and loop

dir discovers what exists

Discover

Know roughly where a tool should live, but not its name? dir lists a module’s contents; the names alone sketch what is on offer:

pprint([name for name in dir(jax.random)
        if not name.startswith('_')][:20], compact=True)
['PRNGKey', 'ball', 'bernoulli', 'beta', 'binomial', 'bits', 'categorical',
 'cauchy', 'chisquare', 'choice', 'clone', 'dirichlet', 'double_sided_maxwell',
 'exponential', 'f', 'fold_in', 'gamma', 'generalized_normal', 'geometric',
 'gumbel']

Skip the _-prefixed internals. In a notebook, module. + Tab gives the same list, filtered as you type, usually the fastest way to turn up a name.

help reads the signature; ?? reads the source

Inspect · read

help(...) prints the docstring: arguments, defaults, return value, often an example.

help(jax.numpy.ones)

In Jupyter, ones? opens the docstring in a side pane, and ones?? shows the source code, which can clarify a terse or ambiguous docstring.

A tiny run settles it

Verify

Docstrings can drift out of date; verify the current behavior with a small call:

jax.numpy.ones(4)
Array([1., 1., 1., 1.], dtype=float32)

The result has the documented shape and values. The discover → inspect → read → verify loop remains useful as APIs change.

Coding assistants enter the same loop

Assistants

An assistant may produce a plausible function and call. Treat the suggestion as a candidate to check before building on it.

Glance at the signature (help / ?), then run a small example. A suggestion that survives both is one you can rely on.

Recap

Wrap-up

  • Discover with dir (or Tab-completion).
  • Inspect with help / ?; read the source with ??.
  • Verify with a tiny run.
  • Assistant answers enter the same loop before you rely on them.