Document that JsonReader methods throw IllegalStateException (goo…

…gle#2670)

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

@@ -418,6 +418,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;
@@ -436,6 +438,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;
@@ -454,6 +458,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;
@@ -471,6 +477,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;
@@ -861,7 +869,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;
@@ -887,7 +895,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;
@@ -920,7 +928,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;
@@ -942,7 +950,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;
@@ -962,7 +970,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}.
@@ -1006,7 +1014,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.
    */
@@ -1243,7 +1251,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.
    */
@@ -1297,7 +1305,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;