update the summary in docstring
document the recently summarised options