Document that JsonReader methods throw IllegalStateException (#2670)

gson/src/main/java/com/google/gson/stream/JsonReader.java

@@ -414,6 +414,8 @@ public final Strictness getStrictness() {
   /**
    * Consumes the next token from the JSON stream and asserts that it is the beginning of a new
    * array.
+   *
+   * @throws IllegalStateException if the next token is not the beginning of an array.
    */
   public void beginArray() throws IOException {
     int p = peeked;
@@ -432,6 +434,8 @@ public void beginArray() throws IOException {
   /**
    * Consumes the next token from the JSON stream and asserts that it is the end of the current
    * array.
+   *
+   * @throws IllegalStateException if the next token is not the end of an array.
    */
   public void endArray() throws IOException {
     int p = peeked;
@@ -450,6 +454,8 @@ public void endArray() throws IOException {
   /**
    * Consumes the next token from the JSON stream and asserts that it is the beginning of a new
    * object.
+   *
+   * @throws IllegalStateException if the next token is not the beginning of an object.
    */
   public void beginObject() throws IOException {
     int p = peeked;
@@ -467,6 +473,8 @@ public void beginObject() throws IOException {
   /**
    * Consumes the next token from the JSON stream and asserts that it is the end of the current
    * object.
+   *
+   * @throws IllegalStateException if the next token is not the end of an object.
    */
   public void endObject() throws IOException {
     int p = peeked;
@@ -857,7 +865,7 @@ private boolean isLiteral(char c) throws IOException {
   /**
    * Returns the next token, a {@link JsonToken#NAME property name}, and consumes it.
    *
-   * @throws IOException if the next token in the stream is not a property name.
+   * @throws IllegalStateException if the next token is not a property name.
    */
   public String nextName() throws IOException {
     int p = peeked;
@@ -883,7 +891,7 @@ public String nextName() throws IOException {
    * Returns the {@link JsonToken#STRING string} value of the next token, consuming it. If the next
    * token is a number, this method will return its string form.
    *
-   * @throws IllegalStateException if the next token is not a string or if this reader is closed.
+   * @throws IllegalStateException if the next token is not a string.
    */
   public String nextString() throws IOException {
     int p = peeked;
@@ -916,7 +924,7 @@ public String nextString() throws IOException {
   /**
    * Returns the {@link JsonToken#BOOLEAN boolean} value of the next token, consuming it.
    *
-   * @throws IllegalStateException if the next token is not a boolean or if this reader is closed.
+   * @throws IllegalStateException if the next token is not a boolean.
    */
   public boolean nextBoolean() throws IOException {
     int p = peeked;
@@ -938,7 +946,7 @@ public boolean nextBoolean() throws IOException {
   /**
    * Consumes the next token from the JSON stream and asserts that it is a literal null.
    *
-   * @throws IllegalStateException if the next token is not null or if this reader is closed.
+   * @throws IllegalStateException if the next token is not a JSON null.
    */
   public void nextNull() throws IOException {
     int p = peeked;
@@ -958,7 +966,7 @@ public void nextNull() throws IOException {
    * token is a string, this method will attempt to parse it as a double using {@link
    * Double#parseDouble(String)}.
    *
-   * @throws IllegalStateException if the next token is not a literal value.
+   * @throws IllegalStateException if the next token is neither a number nor a string.
    * @throws NumberFormatException if the next literal value cannot be parsed as a double.
    * @throws MalformedJsonException if the next literal value is NaN or Infinity and this reader is
    *     not {@link #setStrictness(Strictness) lenient}.
@@ -1002,7 +1010,7 @@ public double nextDouble() throws IOException {
    * token is a string, this method will attempt to parse it as a long. If the next token's numeric
    * value cannot be exactly represented by a Java {@code long}, this method throws.
    *
-   * @throws IllegalStateException if the next token is not a literal value.
+   * @throws IllegalStateException if the next token is neither a number nor a string.
    * @throws NumberFormatException if the next literal value cannot be parsed as a number, or
    *     exactly represented as a long.
    */
@@ -1239,7 +1247,7 @@ private void skipUnquotedValue() throws IOException {
    * token is a string, this method will attempt to parse it as an int. If the next token's numeric
    * value cannot be exactly represented by a Java {@code int}, this method throws.
    *
-   * @throws IllegalStateException if the next token is not a literal value.
+   * @throws IllegalStateException if the next token is neither a number nor a string.
    * @throws NumberFormatException if the next literal value cannot be parsed as a number, or
    *     exactly represented as an int.
    */
@@ -1293,7 +1301,12 @@ public int nextInt() throws IOException {
     return result;
   }
 
-  /** Closes this JSON reader and the underlying {@link Reader}. */
+  /**
+   * Closes this JSON reader and the underlying {@link Reader}.
+   *
+   * <p>Using the JSON reader after it has been closed will throw an {@link IllegalStateException}
+   * in most cases.
+   */
   @Override
   public void close() throws IOException {
     peeked = PEEKED_NONE;