javadocs

platform/core-api/src/com/intellij/psi/PsiReferenceProvider.java

@@ -20,8 +20,14 @@ import com.intellij.util.ProcessingContext;
 import org.jetbrains.annotations.NotNull;
 
 /**
+ * Allows to inject additional references into an element that supports reference contributors.
  * Register it via {@link PsiReferenceContributor} or {@link PsiReferenceProviderBean#EP_NAME}
  *
+ * Note that, if you're implementing a custom language, it won't by default support references registered through PsiReferenceContributor.
+ * If you want to support that, you need to call
+ * {@link com.intellij.psi.impl.source.resolve.reference.ReferenceProvidersRegistry#getReferencesFromProviders(PsiElement)} from your implementation
+ * of PsiElement.getReferences().
+ *
  * @author ik
  */
 public abstract class PsiReferenceProvider {

platform/lang-api/src/com/intellij/psi/PsiReferenceContributor.java

@@ -15,6 +15,11 @@ import com.intellij.openapi.extensions.ExtensionPointName;
  * Some elements return them from {@link PsiElement#getReferences()} directly though, but one should not rely on that
  * behavior since it may be changed in the future.
  *
+ * Note that, if you're implementing a custom language, it won't by default support references registered through PsiReferenceContributor.
+ * If you want to support that, you need to call
+ * {@link com.intellij.psi.impl.source.resolve.reference.ReferenceProvidersRegistry#getReferencesFromProviders(PsiElement)} from your implementation
+ * of PsiElement.getReferences().
+ *
  * The alternative way to register {@link PsiReferenceProvider} is by using {@link PsiReferenceProviderBean}.
  *
  * @author peter