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

@Fire Lancer: Right! I forgot about exception, but I would like to see them mentioned, especially the unchecked 'runtime' exception that this public method could throw

@Mike Stone:

you have to be diligent also to update the docs when you change the semantics of the method.

Mmmm I sure hope that the public API documentation is at the very least updated whenever a change -- that affects the contract of the function -- takes place. If not, those API documentations could be drop altogether.

To add food to yours thoughts (and go with @Scott Dorman), I just stumble upon the future of java7 annotations

What does that means ? That certain 'boundary conditions', rather than being in the documentation, should be better off in the API itself, and automatically used, at compilation time, with appropriate 'assert' generated code.

That way, if a '@CheckForNull' is in the API, the writer of the function might get away with not even documenting it! And if the semantic change, its API will reflect that change (like 'no more @CheckForNull' for instance)

That kind of approach suggests that documentation, for 'boundary conditions', is an extra bonus rather than a mandatory practice.

However, that does not cover the special values of the return object of a function. For that, a complete documentation is still needed.