The code tells you what the code _does_. The documentation (which can include comments in the code) tell you what the code is intended to do. Either one of those can be wrong. If the code doesn't match the documentation, then there is a bug in the system.
Not having documentation just removes the ability to determine if what the code _does_ is what the code is _intended to do_.
> If the code doesn't match the documentation, then there is a bug in the system.
Then I'd say the vast majority of Ruby libraries are buggy.
> Not having documentation just removes the ability to determine if what the code _does_ is what the code is _intended to do_.
But usually there isn't any intent when it comes to async-or-not. Library authors usually just write a method that results in the right value; whether that method can yield or not isn't even something they thought about, much less had a specific design in mind for.
No, source code is where you hide the information, documentation is where you hide misinformation (or accurate information about how the function worked 3 versions ago, which is much the same thing).