[mjr00]

There's often a reason that you want to encapsulate details of the behavior in a library. What if the definition of valid changes in the future and you need to adjust isValid() to also return false if the data matches some other criteria, like being out of bounds? You can say "just change the comment" but the comment is effectively part of your public-facing API and you've just introduced a breaking change.

[TrianguloY]

I see you agree with my point. By introducing a breaking change you need to update the facing api, so what better place to not forget to change the api that to place it exactly where the code is!

[ptx]

If that documented behavior is part of the API contract, then the entire isValid function seems useless and should probably be removed – if it's intended to check emptiness, just use isEmpty which already does that (or rename isValid to isNotEmpty).

[mjr00]

uh, no, I don't agree with your point. Your example is turning a bugfix into a breaking change by describing the implementation details of a method its documentation, which becomes inaccurate after changing the implementation.

Good developers solve this by not describing the implementation details of functions in comments. This is commonly known as encapsulation.[0] This is why most libraries do not have comments detailing the implementation like you suggest.

[0] https://en.wikipedia.org/wiki/Encapsulation_(computer_progra...