I am sorry, but I want to said it: we have tests. Why tests are not for same purpose? (I would say they include it).

As Tudor said:��
"they are way too disconnected from the code"

And this needs to be solved.
We already have nice feature in Nautilus: it shows "test icon" on covered methods. We could extends this idea to simplify test visibility.��

Proposed solution is much simpler. But how much it is practical? How many code could use it?��
For simple cases like String methods is super nice. But could you imaging it for Seaside code? or Morphic?

The goal is not to replace nor to use that for everything.
I'm not looking for the Graal (and tests are not the graal for documentation).

I'm looking for something dead simple that helps me to understand little methods.
It works in python that they also have tons of other ways to tests (probably even a test system that
check on the line level like in Php).

So instead of being defensive we should be more open to improvements when we are talking about documentations.

Stef