Convert null to JsonNull for JsonArray.set (#2170)

* Convert null to JsonNull for `JsonArray.set`

All other methods perform the same implicit conversion.

* Mention null handling in JsonObject documentation

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

@@ -23,9 +23,10 @@
 import java.util.List;
 
 /**
- * A class representing an array type in Json. An array is a list of {@link JsonElement}s each of
+ * A class representing an array type in JSON. An array is a list of {@link JsonElement}s each of
  * which can be of a different type. This is an ordered list, meaning that the order in which
- * elements are added is preserved.
+ * elements are added is preserved. This class does not support {@code null} values. If {@code null}
+ * is provided as element argument to any of the methods, it is converted to a {@link JsonNull}.
  *
  * @author Inderjeet Singh
  * @author Joel Leitch
@@ -128,14 +129,13 @@ public void addAll(JsonArray array) {
 
   /**
    * Replaces the element at the specified position in this array with the specified element.
-   *   Element can be null.
    * @param index index of the element to replace
    * @param element element to be stored at the specified position
    * @return the element previously at the specified position
    * @throws IndexOutOfBoundsException if the specified index is outside the array bounds
    */
   public JsonElement set(int index, JsonElement element) {
-    return elements.set(index, element);
+    return elements.set(index, element == null ? JsonNull.INSTANCE : element);
   }
 
   /**

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

@@ -24,6 +24,8 @@
  * A class representing an object type in Json. An object consists of name-value pairs where names
  * are strings, and values are any other type of {@link JsonElement}. This allows for a creating a
  * tree of JsonElements. The member elements of this object are maintained in order they were added.
+ * This class does not support {@code null} values. If {@code null} is provided as value argument
+ * to any of the methods, it is converted to a {@link JsonNull}.
  *
  * @author Inderjeet Singh
  * @author Joel Leitch

gson/src/test/java/com/google/gson/JsonArrayTest.java

@@ -75,11 +75,18 @@ public void testSet() {
     } catch (IndexOutOfBoundsException expected) {}
     JsonPrimitive a = new JsonPrimitive("a");
     array.add(a);
-    array.set(0, new JsonPrimitive("b"));
+
+    JsonPrimitive b = new JsonPrimitive("b");
+    JsonElement oldValue = array.set(0, b);
+    assertEquals(a, oldValue);
     assertEquals("b", array.get(0).getAsString());
-    array.set(0, null);
-    assertNull(array.get(0));
-    array.set(0, new JsonPrimitive("c"));
+
+    oldValue = array.set(0, null);
+    assertEquals(b, oldValue);
+    assertEquals(JsonNull.INSTANCE, array.get(0));
+
+    oldValue = array.set(0, new JsonPrimitive("c"));
+    assertEquals(JsonNull.INSTANCE, oldValue);
     assertEquals("c", array.get(0).getAsString());
     assertEquals(1, array.size());
   }