Tests should absolutely be next to the code. The test should make it into the documentation. Code is documentation and should make it into the generated documentation, not the first thing you see but it should be there along with commit history, etc.
If that ended up nicely formatted beneath the definition of `foo` in the documentation I would recommend it wholeheartedly. In practice it doesn't happen, sadly.
