added options documentation

@brutski Please review and merge.

I believe this is all accurate based on implemented functionality.  Look at this mainly for functionality and accurate response representations please.

@jlo188 Will be ad hocing and confirming this and hopefully reviewing specs to see if there are differences and open any issues he finds.
Something wrong with formatting I guess. Links at the bottom don't show up when page is rendered