How to document (simple) Java method prerequisites?

Question

It often happens that a method imposes restrictions on its arguments, which cannot be described by a type system. For example, a method may require that any argument be non-empty, or some input argument be positive. There may also be more complex preconditions, for example, that a certain method was previously called or that a certain object is in some state. What is the best way to document this in Javadok?

For example, suppose I have the following public library function, where the argument cannot be negative:

public void foo(int bar) { if (bar < 0) { throw new IllegalArgumentException("Negative bars cannot be food."); } ... } 

I want to document this in such a way that it "stands out" from the rest of the documentation document, so that readers of the documentation immediately know where they should look. I am currently doing this by adding throws sentences to Javadoc:

 /** * Foos a bar. * @param bar the bar to be food * @throws IllegalArgumentException if bar is negative */ public void foo(int bar) { ... 

However, this introduces an exception throw into the specification of the method. Library users can now depend on this behavior in their code. Therefore, if I want to change the method in the next version in such a way as to allow negative parameters, I could break the client code.

Are there any recommendations for documenting such things in Javadoc? I thought:

• Describing in the documentation that the method has undefined behavior if the argument is negative. However, this does not particularly stand out, so many library users may miss it.
• Using annotations ( public void foo(@NonNegative int bar) ). However, for this a standard set of annotations would be ideal, and this standard set does not exist.

Answer 1

You don't seem to dare to rely on your Javadocs API to provide just that: documentation for your API. Although I agree that some developers invariably ignore his warnings, I think that historically Javadocs have been completely adequate in providing sufficient guidance on the proper use of the API. You can go crazy creating all kinds of custom Annotation s, but in the end, people will still implement your API incorrectly.

If you want to go even further than what you already have, you can also implement self-documenting naming conventions where this is practically possible. For instance:

 /** * Foos a positive bar. * @param positiveBar the non-zero,non-negative bar to be food * @throws IllegalArgumentException if bar is zero or negative */ public void foo(int positiveBar) { ... 

Finally, although your question is how to document these restrictions and not handle them, I will say that you should not underestimate the value of IllegalArgumentException . This is exactly what it should be used for, and engineers should not be afraid to throw this exception to indicate a programming error. Developers are not going to go far without reading documents when their implementation is not implemented.

Answer 2

You can create custom javadoc tags , i.e. @pre @inv and @post for the pre , inv ariant and message conditions.

Joshua Bloch further states in Effective Java Second Edition:

The doc comment should list all the prerequisites of the method, which must be true in order for the client to call it, and its postconditions. Typically, preconditions are described implicitly by @throws tags for thrown exceptions; each uncontrolled exception corresponds to a precondition violation. In addition, presets can be specified along with the affected parameters in the @param tags .

Examples:

element index index; must be non-negative and less than the size of this list @throws IndexOutOfBoundsException if the index is out of range ({@code index <0 || index> = this.size ()})

Note that all exceptions begin with , if followed by a sentence describing the conditions under which the exception is thrown. (prerequisite) This is often described using arithmetic expressions.