Yes, exactly - to update the doc so that the next person who needs it will easily find a way to do it (which was not available to you when you created this issue).

The test should assert that what the doc says, so that if someone breaks documented functionality we will immediately know.

Your point about accessing __return__ directly from the prompt is interesting - sure, if that works just document that and make sure the test fails if we make a change that breaks it.