From 05fc121d4562e523acb18aadef537f42d8f669af Mon Sep 17 00:00:00 2001
From: Mateusz Rzeszutek <mrzeszutek@splunk.com>
Date: Tue, 28 Sep 2021 17:15:09 +0200
Subject: [PATCH] fix javadocs

---
 .../instrumentation/api/field/VirtualField.java          | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/field/VirtualField.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/field/VirtualField.java
index f9139639d207..7c447a1c98fe 100644
--- a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/field/VirtualField.java
+++ b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/field/VirtualField.java
@@ -12,8 +12,9 @@
 /**
  * Represents a "virtual" field of type {@code F} that is added to type {@code T} in the runtime.
  *
- * <p>Field values are weakly referenced and will be garbage collected when their owner instance is
- * collected.
+ * <p>A virtual field has similar semantics to a weak-keys strong-values map: the value will be
+ * garbage collected when their owner instance is collected. It is discouraged to use a virtual
+ * field for keeping values that might reference their key, as it may cause memory leaks.
  *
  * @param <T> The type that will contain the new virtual field.
  * @param <F> The field type that'll be added to {@code T}.
@@ -48,14 +49,14 @@ public static <U extends T, T, F> VirtualField<U, F> find(Class<T> type, Class<F
   public abstract void set(T object, @Nullable F fieldValue);
 
   /**
-   * Sets the new value of this virtual field if the current value is {@code null} or absent.
+   * Sets the new value of this virtual field if the current value is {@code null}.
    *
    * @return The old field value if it was present, or the passed {@code fieldValue}.
    */
   public abstract F setIfAbsentAndGet(T object, F fieldValue);
 
   /**
-   * Sets the new value of this virtual field if the current value is {@code null} or absent.
+   * Sets the new value of this virtual field if the current value is {@code null}.
    *
    * @return The old field value if it was present, or the result of evaluating passed {@code
    *     fieldValueSupplier}.