doc: Warn that reference equality might be different than expected in…

… DirectReferenceFilter (#5398)

src/main/java/spoon/reflect/reference/CtReference.java

@@ -19,11 +19,10 @@
 
 
 /**
- * This is the root interface for named program element references. References
- * can point to program element built in the model or not. In the latter case,
- * introspection methods fall back on runtime reflection (
- * <code>java.lang.reflect</code>) to access the program information, as long as
- * available in the classpath.
+ * This is the root interface for named program element references, such as fields, types,
+ * variables, and so on.
+ * If a reference refers to an element in the shadow model, all introspection methods
+ * fall back to reflection where possible, but not all information might be available.
  *
  * @see spoon.reflect.declaration.CtElement
  */

src/main/java/spoon/reflect/visitor/filter/DirectReferenceFilter.java

@@ -10,11 +10,14 @@
 import spoon.reflect.reference.CtReference;
 
 /**
- * This simple filter matches all the references to a given element by using
- * reference equality.
+ * A filter for {@link CtReference}s that compare equal to the reference provided in the constructor.
+ * Note that this does <strong>not</strong> cover all references to the pointed-to element.
+ * If the reference to search for refers to a field, for example, type information is part of the
+ * {@link spoon.reflect.reference.CtVariableReference}. This will cause searches for generic fields
+ * to turn up short, as references with a known type are <em>different</em>.
  */
 public class DirectReferenceFilter<T extends CtReference> extends AbstractFilter<T> {
-	CtReference reference;
+	private final CtReference reference;
 
 	/**
 	 * Creates the filter.