На мой взгляд, лучший способ справиться с этим - снять требование. Измените метод на private и слегка переименуйте его, добавив слово Workload или Internal или что-то еще. Затем создайте новый публичный метод с той же подписью. Пусть этот метод проверит, чтобы убедиться, что вы находитесь в правильном потоке. Если да, вы можете просто выполнить приватный метод. Если нет, то запланируйте выполнение приватного метода в правильном потоке. Таким образом, пользователь 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
}