Java线程JavaDoc

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

不知道有任何这样的标准注释。在第4.5节：记录同步策略中讨论了这个问题。以下几点提示有望帮助您使文档更清晰、更有用：

至少，记录一个类所做的线程安全保证。它是线程安全的吗？它是否在锁定的情况下进行回调？是否存在影响其行为的特定锁？不要强迫客户做出冒险的猜测。如果您不想承诺支持客户端锁定，那没关系，但请这样说。如果您希望客户端能够在类上创建新的原子操作，就像我们在第4.4节中所做的那样，那么您需要记录他们应该获得哪些锁才能安全地执行这些操作。如果您使用锁来保护状态，请为将来的维护人员记录这一点，因为这很容易-使用

@GuardedBy

注释就可以了。如果您使用更微妙的方法来维护线程安全，请记录它们，因为它们对维护人员来说可能并不明显

他们还使用了一些注释，这些注释不是标准的，而是他们推荐的（见附录A）。但是，对于方法，它们只提供了

@GuardedBy

的变体，这不适用于您的情况

---

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

在我看来，最好的处理方法是删除需求。将方法更改为private，并通过添加单词

Workload

或

Internal

或其他内容稍微重命名它。然后创建一个具有相同签名的新公共方法。让这个方法检查你是否在正确的线程上。如果是，您可以只执行private方法。如果没有，则计划在正确的线程上执行私有方法。这样，API的用户就不必担心线程问题，只需调用该方法即可

然后，javadoc中没有什么需要指定的，尽管在公共和私有方法的描述中包含这些信息仍然很有用

这是我需要在EDT上执行某些操作时使用的模式：

/** * Executes something on the EDT with the crazy argument specified. If this is * called outside of the EDT, it will schedule the work to be done on the EDT * as soon as possible. The actual work of this method is found in * {@link #executeSomethingInternal(int)}. * * @argument crazyArgument some crazy argument */ public void executeSomething(int crazyArgument) { if (SwingUtilities.isEventDispatchThread()) { this.executeSomethingInternal(crazyArgument); } else { Runnable r = new Runnable() { private int crazyArgument; public Runnable setCrazyArgument(int crazyArgument) { this.crazyArgument = crazyArgument; return this; } @Override public void run() { this.OuterClass.executeSomethingInternal(this.crazyArgument); } }.setCrazyArgument(crazyArgument); SwingUtilities.invokeLater(r); } } /** * This method actually does the work. It is guaranteed by this class to * always get called on the EDT. Users of this API should call * {@link #executeSomething(int)}. */ private void executeSomethingInternal(int crazyArgument) { // do work here } /** *使用指定的疯狂参数在EDT上执行某些操作。如果这是 *在EDT之外调用，它将安排在EDT上完成的工作 *尽快。该方法的实际工作见 *{@link#executeSomethingInternal（int）}。 * *@argument疯狂的争论 */ 公共无效执行方法（int FRANZYARGUMENT）{ if（SwingUtilities.isEventDispatchThread（））{ 这是一种内在的（疯狂的）； }否则{ Runnable r=新的Runnable（）{ 私家车； 公共可运行设置crazyArgument（内部crazyArgument）{ this.crazyArgument=crazyArgument； 归还这个； } @凌驾 公开募捐{ this.OuterClass.ExecuteMethingInternal（this.crazyArgument）； } }.setCrazyArgument（crazyArgument）； SwingUtilities.invokeLater（r）； } } /** *这种方法实际上起到了作用。该类保证 *总是接到EDT的电话。此API的用户应调用 *{@link#executemething（int）}。 */ 私人无效执行机构内部（内部疯狂担保）{ //你在这里工作吗 }

---

要真正深入了解这一点，您可能还需要在

executesmethinternal

方法中使用断言，如

assert SwingUtilities.isEventDispatchThread（）

作为私有方法，

executesmethinternal

只能从同一类中调用。如果所有调用都在

executemething

中，则无法在EDT之外调用

executemethinginternal

。该断言将确保未来的程序员不会故意或不考虑设计而违反此要求。不幸的是，即使是私有方法也需要文档。@Alison:删除只能在EDT上运行的要求，而不是删除文档要求。如您所见，我实际上在示例代码中包含了文档。