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.
How do you feel about CAS desiredState in addition to options on DELETE? We haven't really talked about this one.