WIP: api documentation

Looking for feedback on the addition of options/desiredState comparison. I have not implemented this yet, but I want to make sure we're in agreement of the changes that need to happen before I move on.
@jonboulle beep