Clear documentation and errors around client_options

[mwhitworth]

see #234

the structure of passing options should be clearer, and any error messages that mention missing client_options should mention their location to aid with diagnosis.