api documentation and “value limits”: do they match?

Question

Do you often see in API documentation (as in \'javadoc of public functions\' for example) the description of \"value limits\" as well as the classic documentation ?

Answer 1

I think those kinds of boundary conditions most definitely belong in the API. However, I would (and often do) go a step further and indicate WHAT those null values mean. Either I indicate it will throw an exception, or I explain what the expected results are when the boundary value is passed in.

It's hard to remember to always do this, but it's a good thing for users of your class. It's also difficult to maintain it if the contract the method presents changes (like null values are changed to no be allowed)... you have to be diligent also to update the docs when you change the semantics of the method.