add documentation for new expectation methods