Java线程JavaDoc [英] Java threading JavaDoc

问题描述

我写了一个只应在特定线程上调用的方法.是否有标准的注释或注释应添加到方法的javadoc中以表示这一点?

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?

推荐答案

不知道任何此类标准注释. Java并发实践在其第4.5节中处理了该问题:记录同步策略 .一些提示可以帮助您使文档清晰和有用:

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:

至少，要记录一个类所提供的线程安全性保证.它是线程安全的吗?它会在持有锁的情况下进行回调吗?是否有任何特定的锁会影响其行为?不要强迫客户做出冒险的猜测.如果您不想承诺支持客户端锁定，那很好，但是要这样说.如果您希望客户能够在类上创建新的原子操作(如我们在4.4节中所做的那样)，则需要记录他们应该安全地获取哪些锁.如果使用锁来保护状态，请为以后的维护者记录下来，因为它很容易-@GuardedBy批注将解决问题.如果您使用更微妙的方法来维护线程安全，请对其进行记录，因为它们对于维护人员而言可能并不明显.

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的变体，不适用于您的情况.

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.

我建议只用普通的Javadoc清楚地记录需求.

I recommend just clearly documenting the requirement in plain Javadoc.

这篇关于Java线程JavaDoc的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！