diff --git a/platform/analysis-api/src/com/intellij/codeInsight/daemon/ImplicitUsageProvider.java b/platform/analysis-api/src/com/intellij/codeInsight/daemon/ImplicitUsageProvider.java
index cfdcd837c031..92efc26f199f 100644
--- a/platform/analysis-api/src/com/intellij/codeInsight/daemon/ImplicitUsageProvider.java
+++ b/platform/analysis-api/src/com/intellij/codeInsight/daemon/ImplicitUsageProvider.java
@@ -21,8 +21,12 @@ import com.intellij.psi.PsiElement;
 
 /**
  * Allows to disable highlighting of certain elements as unused when such elements are not referenced
- * from the code but are referenced in some other way (for example, from generated code).
- *
+ * from the code but are referenced in some other way. For example,
+ * <ul>
+ * <li>from generated code</li>
+ * <li>from outside containers: {@code @javax.servlet.annotation.WebServlet public class MyServlet {}}</li>
+ * <li>from some frameworks: {@code @javax.ejb.EJB private DataStore myInjectedDataStore;}</li> etc
+ * </ul>
  * @author yole
  * @since 6.0
  */
diff --git a/platform/core-api/src/com/intellij/codeInsight/highlighting/ReadWriteAccessDetector.java b/platform/core-api/src/com/intellij/codeInsight/highlighting/ReadWriteAccessDetector.java
index 332ea0054ebc..b7ee80ff4320 100644
--- a/platform/core-api/src/com/intellij/codeInsight/highlighting/ReadWriteAccessDetector.java
+++ b/platform/core-api/src/com/intellij/codeInsight/highlighting/ReadWriteAccessDetector.java
@@ -24,7 +24,14 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
- * @author yole
+ * This extension is used in Find Usages, Highlighting and other places to
+ * classify the psi expression as:
+ * <ul>
+ * <li>read variable expression (e.g. {@code int var = expression;} ), see {@link Access#Read}</li>
+ * <li>write variable expression (e.g. {@code expression = value;} ), see {@link Access#Write}</li> or
+ * <li>read/write variable expression (e.g. {@code var++;} ), see {@link Access#ReadWrite}</li>
+ * </ul>
+ *
  */
 public abstract class ReadWriteAccessDetector {
   public static final ExtensionPointName<ReadWriteAccessDetector> EP_NAME = ExtensionPointName.create("com.intellij.readWriteAccessDetector");