I prefer to put that kind of stuff in the javadocs/xmldocs, but I mostly work in C#/Java, with IDEs that have tooling baked in that make generating that kind of documentation A.) really easy to generate and B.) very useful in auto-complete lists, mouse-over popups, etc.

Ideally, you'd have some tests as well that would test those kind of corner-cases and illustrate failure cases and expected outputs.