Clarify in documentation that Gson might cache strategy results (#2215)

* Clarify in documentation that Gson might cache strategy results

* Improve wording; mention that adapter factory results are cached as well

gson/src/main/java/com/google/gson/GsonBuilder.java

@@ -362,6 +362,10 @@ public GsonBuilder setFieldNamingPolicy(FieldNamingPolicy namingConvention) {
    * Configures Gson to apply a specific naming strategy to an object's fields during
    * serialization and deserialization.
    *
+   * <p>The created Gson instance might only use the field naming strategy once for a
+   * field and cache the result. It is not guaranteed that the strategy will be used
+   * again every time the value of a field is serialized or deserialized.
+   *
    * @param fieldNamingStrategy the naming strategy to apply to the fields
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.3
@@ -415,6 +419,10 @@ public GsonBuilder setNumberToNumberStrategy(ToNumberStrategy numberToNumberStra
    * JSON null is written to output, and when deserialized the JSON value is skipped and
    * {@code null} is returned.
    *
+   * <p>The created Gson instance might only use an exclusion strategy once for a field or
+   * class and cache the result. It is not guaranteed that the strategy will be used again
+   * every time the value of a field or a class is serialized or deserialized.
+   *
    * @param strategies the set of strategy object to apply during object (de)serialization.
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 1.4
@@ -620,6 +628,10 @@ public GsonBuilder registerTypeAdapter(Type type, Object typeAdapter) {
    * is designed to handle a large number of factories, so you should consider registering
    * them to be at par with registering an individual type adapter.
    *
+   * <p>The created Gson instance might only use the factory once to create an adapter for
+   * a specific type and cache the result. It is not guaranteed that the factory will be used
+   * again every time the type is serialized or deserialized.
+   *
    * @since 2.1
    */
   public GsonBuilder registerTypeAdapterFactory(TypeAdapterFactory factory) {
@@ -716,6 +728,10 @@ public GsonBuilder disableJdkUnsafe() {
    * all classes for which no {@link TypeAdapter} has been registered, and for which no
    * built-in Gson {@code TypeAdapter} exists.
    *
+   * <p>The created Gson instance might only use an access filter once for a class or its
+   * members and cache the result. It is not guaranteed that the filter will be used again
+   * every time a class or its members are accessed during serialization or deserialization.
+   *
    * @param filter filter to add
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    * @since 2.9.1

gson/src/main/java/com/google/gson/annotations/JsonAdapter.java

@@ -16,6 +16,7 @@
 
 package com.google.gson.annotations;
 
+import com.google.gson.Gson;
 import com.google.gson.JsonDeserializer;
 import com.google.gson.JsonSerializer;
 import com.google.gson.TypeAdapter;
@@ -60,7 +61,7 @@
  * </pre>
  *
  * Since User class specified UserJsonAdapter.class in &#64;JsonAdapter annotation, it
- * will automatically be invoked to serialize/deserialize User instances. <br>
+ * will automatically be invoked to serialize/deserialize User instances.
  *
  * <p> Here is an example of how to apply this annotation to a field.
  * <pre>
@@ -80,9 +81,14 @@
  *
  * <p>The class referenced by this annotation must be either a {@link
  * TypeAdapter} or a {@link TypeAdapterFactory}, or must implement one
- * or both of {@link JsonDeserializer} or {@link JsonSerializer}. 
- * Using {@link TypeAdapterFactory} makes it possible to delegate 
- * to the enclosing {@code Gson} instance.
+ * or both of {@link JsonDeserializer} or {@link JsonSerializer}.
+ * Using {@link TypeAdapterFactory} makes it possible to delegate
+ * to the enclosing {@link Gson} instance.
+ *
+ * <p>{@code Gson} instances might cache the adapter they create for
+ * a {@code @JsonAdapter} annotation. It is not guaranteed that a new
+ * adapter is created every time the annotated class or field is serialized
+ * or deserialized.
  *
  * @since 2.3
  *