Java threading JavaDoc

Question

I have written a method which should only be called on a particular thread. Is there a standard annotation or note which should be added to the method's javadoc to denote this?

Answer 1

Don't know of any such standard annotations. Java Concurrency in Practice deals with the question in its section 4.5: Documenting Synchronization Policies. A few hints which hopefully help you make your documentation clear and useful:

At the very least, document the thread safety guarantees made by a class. Is it thread-safe? Does it make callbacks with a lock held? Are there any specific locks that affect its behavior? Don't force clients to make risky guesses. If you don't want to commit to supporting client-side locking, that's fine, but say so. If you want clients to be able to create new atomic operations on your class, as we did in Section 4.4, you need to document which locks they should acquire to do so safely. If you use locks to guard state, document this for future maintainers, because it's so easy - the @GuardedBy annotation will do the trick. If you use more subtle means to maintain thread safety, document them because they may not be obvious to maintainers.

They also use some annotations, which are not standard, but recommended by them (see Appendix A). However, for methods they only offer variations of @GuardedBy, which is not applicable to your case.

I recommend just clearly documenting the requirement in plain Javadoc.