Changed BlockingContext to BlockingExecutor and added example to javadoc

Nikita Katkov · Nikita Katkov · commit ec7d51082622 · 2021-09-27T17:09:36.000+03:00
diff --git a/java8/src/main/java/org/jetbrains/annotations/BlockingExecutor.java b/java8/src/main/java/org/jetbrains/annotations/BlockingExecutor.java
@@ -19,10 +19,32 @@
 import java.lang.annotation.*;
 
 /**
- * Indicates that the annotated execution context (e.g. coroutine dispatcher, scheduler, etc.) allows blocking calls inside.
+ * Indicates that the annotated executor (e.g. coroutine dispatcher, scheduler, etc.)
+ * allows blocking methods execution.
+ *
+ * If a given context does not allow blocking calls, {@link NonBlockingExecutor} should be used.
+ *
+ * Example:
+ * <pre>
+ * {@code
+ *  class ExampleService {
+ *      @BlockingContext
+ *      val dispatcher: CoroutineContext
+ *          get() { ... }
+ *
+ *      suspend fun foo() {
+ *          val result = withContext(dispatcher) {
+ *              blockingBuzz() // no IDE warning
+ *          }
+ *      }
+ *
+ *      @Blocking fun blockingBuzz() { ... }
+ *  }
+ * }
+ * </pre>
  */
 @Documented
 @Retention(RetentionPolicy.CLASS)
 @Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE_USE})
-public @interface BlockingContext {
+public @interface BlockingExecutor {
 }
diff --git a/java8/src/main/java/org/jetbrains/annotations/NonBlockingExecutor.java b/java8/src/main/java/org/jetbrains/annotations/NonBlockingExecutor.java
@@ -19,10 +19,32 @@
 import java.lang.annotation.*;
 
 /**
- * Indicates that the annotated execution context (e.g. coroutine dispatcher, scheduler, etc.) does not allow blocking calls inside.
+ * Indicates that the annotated executor (e.g. coroutine dispatcher, scheduler, etc.)
+ * does not allow blocking methods execution.
+ *
+ * If a given context allows blocking calls, {@link BlockingExecutor} should be used.
+ *
+ * Example:
+ * <pre>
+ * {@code
+ *  class ExampleService {
+ *      @NonBlockingContext
+ *      val dispatcher: CoroutineContext
+ *          get() { ... }
+ *
+ *      suspend fun foo() {
+ *          val result = withContext(dispatcher) {
+ *              blockingBuzz() // IDE warning: `Possibly blocking call in non-blocking context`
+ *          }
+ *      }
+ *
+ *      @Blocking fun blockingBuzz() { ... }
+ *  }
+ * }
+ * </pre>
  */
 @Documented
 @Retention(RetentionPolicy.CLASS)
 @Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE_USE})
-public @interface NonBlockingContext {
+public @interface NonBlockingExecutor {
 }
