Java线程化JavaDoc

Question

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

Answer 1

不知道有任何这样的标准注释。《Java 并发实践》在 4.5 节：记录同步策略中处理了这个问题。一些提示希望可以帮助您使文档清晰有用：

至少，记录一个类所做的线程安全保证。它是线程安全的吗？它会在持有锁的情况下进行回调吗？是否有任何特定的锁会影响其行为？不要强迫客户做出冒险的猜测。如果您不想承诺支持客户端锁定，那也可以，但要这么说。如果您希望客户端能够在您的类上创建新的原子操作，就像我们在第 4.4 节中所做的那样，您需要记录它们应该获取哪些锁才能安全地执行此操作。如果您使用锁来保护状态，请为未来的维护人员记录下来，因为它非常简单 - 注释@GuardedBy就可以解决问题。如果您使用更微妙的方法来维护线程安全，请记录它们，因为它们对维护人员来说可能并不明显。

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

我建议用简单的 Javadoc 清楚地记录需求。