Updated API doc with new specs

These are not yet reflected in the code... I made an unfortunate
number of last minute design tweaks... but the result should be
much nicer to use.