l.b.a.treelookup : module documentation

Part of lp.bugs.adapters

Construct and search simple tree structures.

`LookupTree` encapsulates a simple tree structure that can be used to
do lookups using one or more keys. This was originally created to
support mapping statuses from remote bug trackers into Launchpad
statuses.

Another main criteria was documentation. We want to be able to
automatically generate documentation from the lookup trees that are
specified.

Originally a simple dictionary lookup was attempted, but it proved
difficult to create some of the moderately complex mapping rules we
needed. Supporting defaults and such required additional logic, and
ordering was lost, which may be useful to document.

Secondly, a structure of tuples was attempted, and this proved easier
to construct. However, it proved difficult to see what was going on,
with brackets everywhere!

The final design is a compromise. `LookupTree` and `LookupBranch` both
feel tuple-like when constructing lookup trees in code, especially
because `LookupTree` will promote any regular tuples it's given into
`LookupBranch`es, but they store branches and keys as instance
attributes. They encapsulate the searching algorithm and a few other
conveniences. This makes the generation of lookup trees quite pleasant
on the eye, makes debugging easier, and means they can be customised.