Update custom type_caster doc with a more complete example

[tjcorona]

I have recently come across strange errors (XXX undetected error) when calling overloaded methods that take as input objects that have custom type_caster instantiations. After some debugging, I found that a custom pybind11 type_caster<>::load(handle,bool) method must not only return a bool to denote its successful conversion, but must also throw a reference_cast_error() when the handle is not the expected type (to facilitate its use in pybind11's try/catch dispatch for overloaded methods). Also, the failed attempts to convert the handle likely raise a python error which, if left uncleared, will manifest in strange behavior elsewhere in the program. The readthedocs for custom type casters doesn't really cover these crucial requirements on the load method. It would have been useful for me to read about this in the documentation, so I figure it would probably be useful for someone else to read it too!

[tjcorona]

If you'd like, I can take a stab at updating your doc and put up a merge request. Just let me know!

[wjakob]

Please do -- that would be great!