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.
@bcwaldon actually in that case really we should CAS the "previous desired state" on other operations, right?