update doco to include details of response messges