doc and tests for object event return instead of fd.  implementation to come