more consistent error handling.

mostly: giving back EINVAL when a null struct ookfile is passed.
more manpages; completes initial set.

all of the major API calls are at least moderately documented,
now.