Java线程JavaDoc

我不知道有这样的标准注解。 Java Concurrency in Practice 记录同步策略 . 以下几点提示有助于您使文档更清晰、更有用:

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

他们还使用了一些注释,这些注释不是标准的,而是他们推荐的(见附录A)。但是,对于方法,它们只提供 @守卫者 ,这不适用于您的情况。

我建议用纯Javadoc清楚地记录需求。

在我看来,处理这个问题的最好办法就是取消这个要求。将方法更改为private,并通过添加 Workload Internal

然后,在javadoc中没有要指定的内容,尽管在public和private方法的描述中包含这些信息仍然很有用。

/**
 * 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
}