Java 线程 JavaDoc

Question

我已经编写了一个只应在特定线程上调用的方法。是否应将标准注释或注释添加到方法的 javadoc 中以表示这一点？

Answer 1

不知道有任何这样的标准注释。 Java Concurrency in Practice在其第 4.5 节中处理了这个问题:记录同步策略。希望能帮助您使文档清晰有用的一些提示:

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.

他们还使用了一些注解，这些注解不是标准的，而是他们推荐的(见附录 A)。但是，对于方法，他们只提供 @GuardedBy 的变体，这不适用于您的情况。

我建议只在普通 Javadoc 中清楚地记录需求。