Basic doc fixes

@greysteil Would you mind taking a peek at this? 
@greysteil Hm, we use 'Returns' as the header here ~60 times in the docs. Think we should update the lot to be either "Response" (for HTTP requests) or "Return value" (for link generation and libraries)