Reformat

src/main/java/com/drtshock/playervaults/PlayerVaults.java

@@ -25,18 +25,7 @@ import com.drtshock.playervaults.util.Metrics;
 import com.drtshock.playervaults.util.Updater;
 import com.drtshock.playervaults.vaultmanagement.VaultManager;
 import com.drtshock.playervaults.vaultmanagement.VaultViewInfo;
-
-import java.io.File;
-import java.io.FileOutputStream;
-import java.io.IOException;
-import java.io.InputStream;
-import java.io.OutputStream;
-import java.util.HashMap;
-import java.util.logging.Level;
-import java.util.logging.Logger;
-
 import net.milkbowl.vault.economy.Economy;
-
 import org.bukkit.Bukkit;
 import org.bukkit.configuration.file.YamlConfiguration;
 import org.bukkit.entity.Player;
@@ -45,6 +34,11 @@ import org.bukkit.plugin.RegisteredServiceProvider;
 import org.bukkit.plugin.java.JavaPlugin;
 import org.bukkit.scheduler.BukkitRunnable;
 
+import java.io.*;
+import java.util.HashMap;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
 public class PlayerVaults extends JavaPlugin {
 
     public static PlayerVaults PLUGIN;
@@ -94,7 +88,7 @@ public class PlayerVaults extends JavaPlugin {
         new File(DIRECTORY + File.separator + "backups").mkdirs();
         VM = new VaultManager(this);
 
-        if(getConfig().getBoolean("cleanup.enable", false)) {
+        if (getConfig().getBoolean("cleanup.enable", false)) {
             getServer().getScheduler().runTaskAsynchronously(this, new Cleanup(getConfig().getInt("cleanup.lastEdit", 30)));
         }
     }

src/main/java/com/drtshock/playervaults/commands/Commands.java

@@ -16,12 +16,10 @@
  */
 package com.drtshock.playervaults.commands;
 
-import com.drtshock.playervaults.vaultmanagement.VaultOperations;
-import com.drtshock.playervaults.vaultmanagement.VaultViewInfo;
 import com.drtshock.playervaults.PlayerVaults;
 import com.drtshock.playervaults.util.Lang;
-import java.util.Set;
+import com.drtshock.playervaults.vaultmanagement.VaultOperations;
-
+import com.drtshock.playervaults.vaultmanagement.VaultViewInfo;
 import org.bukkit.ChatColor;
 import org.bukkit.command.Command;
 import org.bukkit.command.CommandExecutor;

src/main/java/com/drtshock/playervaults/commands/SignSetInfo.java

@@ -17,8 +17,8 @@
 package com.drtshock.playervaults.commands;
 
 /**
- * A class for setting signs. Stores information about the sign owner, number,
+ * A class for setting signs. Stores information about the sign owner, number, and whether or not is opens a self vault
- * and whether or not is opens a self vault or another person's vault.
+ * or another person's vault.
  */
 public class SignSetInfo {
 
@@ -48,8 +48,7 @@ public class SignSetInfo {
     }
 
     /**
-     * Get whether or not the sign will open their own vault or another
+     * Get whether or not the sign will open their own vault or another person's.
-     * person's.
      *
      * @return Whether or not it is a 'self' sign.
      */

src/main/java/com/drtshock/playervaults/listeners/Listeners.java

@@ -17,13 +17,10 @@
 package com.drtshock.playervaults.listeners;
 
 import com.drtshock.playervaults.PlayerVaults;
-import com.drtshock.playervaults.vaultmanagement.VaultOperations;
-import com.drtshock.playervaults.vaultmanagement.VaultViewInfo;
 import com.drtshock.playervaults.util.Lang;
 import com.drtshock.playervaults.vaultmanagement.VaultManager;
-
+import com.drtshock.playervaults.vaultmanagement.VaultOperations;
-import java.io.IOException;
+import com.drtshock.playervaults.vaultmanagement.VaultViewInfo;
-
 import org.bukkit.ChatColor;
 import org.bukkit.Location;
 import org.bukkit.Material;
@@ -40,13 +37,11 @@ import org.bukkit.event.block.BlockPhysicsEvent;
 import org.bukkit.event.entity.EntityChangeBlockEvent;
 import org.bukkit.event.entity.PlayerDeathEvent;
 import org.bukkit.event.inventory.InventoryCloseEvent;
-import org.bukkit.event.player.PlayerInteractEntityEvent;
+import org.bukkit.event.player.*;
-import org.bukkit.event.player.PlayerInteractEvent;
-import org.bukkit.event.player.PlayerJoinEvent;
-import org.bukkit.event.player.PlayerQuitEvent;
-import org.bukkit.event.player.PlayerTeleportEvent;
 import org.bukkit.inventory.Inventory;
 
+import java.io.IOException;
+
 public class Listeners implements Listener {
 
     public PlayerVaults plugin;
@@ -54,6 +49,7 @@ public class Listeners implements Listener {
     public Listeners(PlayerVaults playerVaults) {
         this.plugin = playerVaults;
     }
+
     VaultManager vm = new VaultManager(plugin);
 
     public void saveVault(Player player) {
@@ -203,8 +199,7 @@ public class Listeners implements Listener {
     }
 
     /**
-     * Check if the location given is a sign, and if so, remove it from the
+     * Check if the location given is a sign, and if so, remove it from the signs.yml file
-     * signs.yml file
      *
      * @param location The location to check
      */

src/main/java/com/drtshock/playervaults/tasks/Cleanup.java

@@ -17,11 +17,11 @@ public class Cleanup extends BukkitRunnable {
     @Override
     public void run() {
         File file = new File(PlayerVaults.DIRECTORY);
-        if(!file.exists()) return;
+        if (!file.exists()) return;
 
         long time = System.currentTimeMillis();
-        for(File f : file.listFiles()) {
+        for (File f : file.listFiles()) {
-            if(time - f.lastModified() > diff) {
+            if (time - f.lastModified() > diff) {
                 f.delete();
                 PlayerVaults.PLUGIN.getLogger().info("Deleting vault file: " + f.getName());
             }

src/main/java/com/drtshock/playervaults/util/Lang.java

@@ -52,6 +52,7 @@ public enum Lang {
 
     /**
      * Lang enum constructor.
+     *
      * @param path The string path.
      * @param start The default string.
      */
@@ -62,6 +63,7 @@ public enum Lang {
 
     /**
      * Set the {@code YamlConfiguration} to use.
+     *
      * @param config The config to set.
      */
     public static void setFile(YamlConfiguration config) {
@@ -77,6 +79,7 @@ public enum Lang {
 
     /**
      * Get the default value of the path.
+     *
      * @return The default value of the path.
      */
     public String getDefault() {
@@ -85,6 +88,7 @@ public enum Lang {
 
     /**
      * Get the path to the string.
+     *
      * @return The path to the string.
      */
     public String getPath() {

src/main/java/com/drtshock/playervaults/util/Metrics.java

@@ -34,23 +34,12 @@ import org.bukkit.plugin.Plugin;
 import org.bukkit.plugin.PluginDescriptionFile;
 import org.bukkit.scheduler.BukkitTask;
 
-import java.io.BufferedReader;
+import java.io.*;
-import java.io.ByteArrayOutputStream;
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStreamReader;
-import java.io.OutputStream;
-import java.io.UnsupportedEncodingException;
 import java.net.Proxy;
 import java.net.URL;
 import java.net.URLConnection;
 import java.net.URLEncoder;
-import java.util.Collections;
+import java.util.*;
-import java.util.HashSet;
-import java.util.Iterator;
-import java.util.LinkedHashSet;
-import java.util.Set;
-import java.util.UUID;
 import java.util.logging.Level;
 import java.util.zip.GZIPOutputStream;
 
@@ -148,6 +137,7 @@ public class Metrics {
      * website. Plotters can be added to the graph object returned.
      *
      * @param name The name of the graph
+     *
      * @return Graph object created. Will never return NULL under normal circumstances unless bad parameters are given
      */
     public Graph createGraph(final String name) {
@@ -488,6 +478,7 @@ public class Metrics {
      * GZip compress a string of bytes
      *
      * @param input
+     *
      * @return
      */
     public static byte[] gzip(String input) {
@@ -529,6 +520,7 @@ public class Metrics {
      * @param json
      * @param key
      * @param value
+     *
      * @throws UnsupportedEncodingException
      */
     private static void appendJSONPair(StringBuilder json, String key, String value) throws UnsupportedEncodingException {
@@ -561,6 +553,7 @@ public class Metrics {
      * Escape a string to create a valid JSON string
      *
      * @param text
+     *
      * @return
      */
     private static String escapeJSON(String text) {
@@ -607,6 +600,7 @@ public class Metrics {
      * Encode text as UTF-8
      *
      * @param text the text to encode
+     *
      * @return the encoded text, as UTF-8
      */
     private static String urlEncode(final String text) throws UnsupportedEncodingException {

src/main/java/com/drtshock/playervaults/util/Updater.java

@@ -1,5 +1,11 @@
 package com.drtshock.playervaults.util;
 
+import org.bukkit.configuration.file.YamlConfiguration;
+import org.bukkit.plugin.Plugin;
+import org.json.simple.JSONArray;
+import org.json.simple.JSONObject;
+import org.json.simple.JSONValue;
+
 import java.io.*;
 import java.net.MalformedURLException;
 import java.net.URL;
@@ -9,24 +15,18 @@ import java.util.logging.Level;
 import java.util.zip.ZipEntry;
 import java.util.zip.ZipFile;
 
-import org.bukkit.configuration.file.YamlConfiguration;
-import org.bukkit.plugin.Plugin;
-import org.json.simple.JSONArray;
-import org.json.simple.JSONObject;
-import org.json.simple.JSONValue;
-
 /**
  * Check dev.bukkit.org to find updates for a given plugin, and download the updates if needed.
  * <p/>
- * <b>VERY, VERY IMPORTANT</b>: Because there are no standards for adding auto-update toggles in your plugin's config, this system provides NO CHECK WITH YOUR CONFIG to make sure the user has allowed auto-updating.
+ * <b>VERY, VERY IMPORTANT</b>: Because there are no standards for adding auto-update toggles in your plugin's config,
- * <br>
+ * this system provides NO CHECK WITH YOUR CONFIG to make sure the user has allowed auto-updating. <br> It is a
- * It is a <b>BUKKIT POLICY</b> that you include a boolean value in your config that prevents the auto-updater from running <b>AT ALL</b>.
+ * <b>BUKKIT POLICY</b> that you include a boolean value in your config that prevents the auto-updater from running
- * <br>
+ * <b>AT ALL</b>. <br> If you fail to include this option in your config, your plugin will be <b>REJECTED</b> when you
- * If you fail to include this option in your config, your plugin will be <b>REJECTED</b> when you attempt to submit it to dev.bukkit.org.
+ * attempt to submit it to dev.bukkit.org.
  * <p/>
- * An example of a good configuration option would be something similar to 'auto-update: true' - if this value is set to false you may NOT run the auto-updater.
+ * An example of a good configuration option would be something similar to 'auto-update: true' - if this value is set to
- * <br>
+ * false you may NOT run the auto-updater. <br> If you are unsure about these rules, please read the plugin submission
- * If you are unsure about these rules, please read the plugin submission guidelines: http://goo.gl/8iU5l
+ * guidelines: http://goo.gl/8iU5l
  *
  * @author Gravity
  */
@@ -92,7 +92,8 @@ public class Updater {
          */
         FAIL_DBO,
         /**
-         * When running the version check, the file on DBO did not contain the a version in the format 'vVersion' such as 'v1.0'.
+         * When running the version check, the file on DBO did not contain the a version in the format 'vVersion' such
+         * as 'v1.0'.
          */
         FAIL_NOVERSION,
         /**
@@ -132,7 +133,8 @@ public class Updater {
      *
      * @param plugin The plugin that is checking for an update.
      * @param id The dev.bukkit.org id of the project
-     * @param file     The file that the plugin is running from, get this by doing this.getFile() from within your main class.
+     * @param file The file that the plugin is running from, get this by doing this.getFile() from within your main
+     * class.
      * @param type Specify the type of update this will be. See {@link UpdateType}
      * @param announce True if the program should announce the progress of new updates in console
      */
@@ -230,8 +232,8 @@ public class Updater {
     }
 
     /**
-     * As the result of Updater output depends on the thread's completion, it is necessary to wait for the thread to finish
+     * As the result of Updater output depends on the thread's completion, it is necessary to wait for the thread to
-     * before allowing anyone to check the result.
+     * finish before allowing anyone to check the result.
      */
     private void waitForThread() {
         if (thread != null && thread.isAlive()) {
@@ -378,7 +380,8 @@ public class Updater {
     }
 
     /**
-     * Check if the name of a jar is one of the plugins currently installed, used for extracting the correct files out of a zip.
+     * Check if the name of a jar is one of the plugins currently installed, used for extracting the correct files out
+     * of a zip.
      */
     private boolean pluginFile(String name) {
         for (File file : new File("plugins").listFiles()) {
@@ -390,7 +393,8 @@ public class Updater {
     }
 
     /**
-     * Check to see if the program should continue by evaluation whether the plugin is already updated, or shouldn't be updated
+     * Check to see if the program should continue by evaluation whether the plugin is already updated, or shouldn't be
+     * updated
      */
     private boolean versionCheck(String title) {
         if (type != Updater.UpdateType.NO_VERSION_CHECK) {

src/main/java/com/drtshock/playervaults/vaultmanagement/EconomyOperations.java

@@ -18,17 +18,15 @@ package com.drtshock.playervaults.vaultmanagement;
 
 import com.drtshock.playervaults.PlayerVaults;
 import com.drtshock.playervaults.util.Lang;
-
-import java.io.File;
-import java.io.IOException;
-
 import net.milkbowl.vault.economy.EconomyResponse;
-
 import org.bukkit.ChatColor;
 import org.bukkit.configuration.InvalidConfigurationException;
 import org.bukkit.configuration.file.YamlConfiguration;
 import org.bukkit.entity.Player;
 
+import java.io.File;
+import java.io.IOException;
+
 /**
  * A class that handles all economy operations.
  */
@@ -48,6 +46,7 @@ public class EconomyOperations {
      *
      * @param player The player to pay.
      * @param number The vault number to open.
+     *
      * @return The transaction success.
      */
     public static boolean payToOpen(Player player, int number) {
@@ -71,6 +70,7 @@ public class EconomyOperations {
      * Have a player pay to create a vault.
      *
      * @param player The player to pay.
+     *
      * @return The transaction success
      */
     public static boolean payToCreate(Player player) {
@@ -92,6 +92,7 @@ public class EconomyOperations {
      *
      * @param player The player to receive the money.
      * @param number The vault number to delete.
+     *
      * @return The transaction success.
      */
     public static boolean refundOnDelete(Player player, int number) {

src/main/java/com/drtshock/playervaults/vaultmanagement/Serialization.java

@@ -16,13 +16,6 @@
  */
 package com.drtshock.playervaults.vaultmanagement;
 
-import java.util.ArrayList;
-import java.util.HashMap;
-import java.util.Iterator;
-import java.util.List;
-import java.util.Map;
-import java.util.Map.Entry;
-
 import org.bukkit.Bukkit;
 import org.bukkit.ChatColor;
 import org.bukkit.configuration.serialization.ConfigurationSerializable;
@@ -33,11 +26,13 @@ import org.json.JSONArray;
 import org.json.JSONException;
 import org.json.JSONObject;
 
+import java.util.*;
+import java.util.Map.Entry;
+
 /**
  * Fancy JSON serialization mostly by evilmidget38.
  *
  * @author evilmidget38, gomeow
- *
  */
 public class Serialization {
 

src/main/java/com/drtshock/playervaults/vaultmanagement/VaultHolder.java

@@ -20,8 +20,7 @@ import org.bukkit.inventory.Inventory;
 import org.bukkit.inventory.InventoryHolder;
 
 /**
- * Represents a VaultHolder to assist in detection of Player Vaults from other
+ * Represents a VaultHolder to assist in detection of Player Vaults from other plugins.
- * plugins.
  */
 public class VaultHolder implements InventoryHolder {
 

src/main/java/com/drtshock/playervaults/vaultmanagement/VaultManager.java

@@ -18,23 +18,20 @@ package com.drtshock.playervaults.vaultmanagement;
 
 import com.drtshock.playervaults.PlayerVaults;
 import com.drtshock.playervaults.util.Lang;
-
-import java.io.File;
-import java.io.IOException;
-import java.util.ArrayList;
-import java.util.List;
-
 import org.bukkit.Bukkit;
-import org.bukkit.ChatColor;
 import org.bukkit.command.CommandSender;
 import org.bukkit.configuration.file.FileConfiguration;
 import org.bukkit.configuration.file.YamlConfiguration;
 import org.bukkit.entity.Player;
 import org.bukkit.inventory.Inventory;
 
+import java.io.File;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.List;
+
 /**
- * A class for managing actual IO to the files, loading inventories, and saving
+ * A class for managing actual IO to the files, loading inventories, and saving them.
- * them.
  */
 public class VaultManager {
 
@@ -43,6 +40,7 @@ public class VaultManager {
     public VaultManager(PlayerVaults instance) {
         this.plugin = instance;
     }
+
     private final String directory = "plugins" + File.separator + "PlayerVaults" + File.separator + "vaults";
 
     /**
@@ -51,6 +49,7 @@ public class VaultManager {
      * @param inventory The inventory to be saved.
      * @param player The player of whose file to save to.
      * @param number The vault number.
+     *
      * @throws IOException Uh oh!
      */
     public void saveVault(Inventory inventory, String player, int number) throws IOException {
@@ -92,7 +91,7 @@ public class VaultManager {
             if (playerFile.getConfigurationSection("vault" + number) == null) {
                 VaultHolder vaultHolder = new VaultHolder(number);
                 Player player = Bukkit.getPlayer(holder);
-                if(player == null) {
+                if (player == null) {
                     return null;
                 }
                 if (EconomyOperations.payToCreate(player)) {
@@ -145,12 +144,12 @@ public class VaultManager {
     }
 
     /**
-     * Get an inventory from file. Returns null if the inventory doesn't exist.
+     * Get an inventory from file. Returns null if the inventory doesn't exist. SHOULD ONLY BE USED INTERNALLY
-     * SHOULD ONLY BE USED INTERNALLY
      *
      * @param playerFile the YamlConfiguration file.
      * @param size the size of the vault.
      * @param number the vault number.
+     *
      * @return inventory if exists, otherwise null.
      */
     private Inventory getInventory(YamlConfiguration playerFile, int size, int number) {
@@ -167,11 +166,11 @@ public class VaultManager {
     }
 
     /**
-     * Gets an inventory without storing references to it. Used for dropping a
+     * Gets an inventory without storing references to it. Used for dropping a players inventories on death.
-     * players inventories on death.
      *
      * @param holder The holder of the vault.
      * @param number The vault number.
+     *
      * @return The inventory of the specified holder and vault number.
      */
     public Inventory getVault(String holder, int number) {
@@ -199,12 +198,13 @@ public class VaultManager {
      * @param sender The sender of whom to send messages to.
      * @param holder The vault holder.
      * @param number The vault number.
+     *
      * @throws IOException Uh oh!
      */
     public void deleteVault(CommandSender sender, String holder, int number) throws IOException {
         String name = holder.toLowerCase();
         File file = new File(directory + File.separator + name.toLowerCase() + ".yml");
-        if(!file.exists()) {
+        if (!file.exists()) {
             return;
         }
         FileConfiguration playerFile = YamlConfiguration.loadConfiguration(file);
@@ -223,6 +223,7 @@ public class VaultManager {
      * Get the holder's vault file. Create if doesn't exist.
      *
      * @param holder The vault holder.
+     *
      * @return The holder's vault config file.
      */
     public YamlConfiguration getPlayerVaultFile(String holder) {
@@ -247,6 +248,7 @@ public class VaultManager {
      *
      * @param holder The vault holder of whose file to save.
      * @param yaml The config to save.
+     *
      * @throws IOException Uh oh!
      */
     public void saveFile(String holder, YamlConfiguration yaml) throws IOException {

src/main/java/com/drtshock/playervaults/vaultmanagement/VaultOperations.java

@@ -18,23 +18,22 @@ package com.drtshock.playervaults.vaultmanagement;
 
 import com.drtshock.playervaults.PlayerVaults;
 import com.drtshock.playervaults.util.Lang;
-
-import java.io.IOException;
-
 import org.bukkit.Bukkit;
 import org.bukkit.ChatColor;
 import org.bukkit.command.CommandSender;
 import org.bukkit.entity.Player;
 import org.bukkit.inventory.Inventory;
 
+import java.io.IOException;
+
 public class VaultOperations {
 
     /**
-     * Check whether or not the player has permission to open the requested
+     * Check whether or not the player has permission to open the requested vault.
-     * vault.
      *
      * @param sender The person to check.
      * @param number The vault number.
+     *
      * @return Whether or not they have permission.
      */
     public static boolean checkPerms(CommandSender sender, int number) {
@@ -53,8 +52,8 @@ public class VaultOperations {
      * Get the max size vault a player is allowed to have.
      *
      * @param player that is having his permissions checked.
-     * @return max size as integer. If no max size is set then it will default
+     *
-     * to 54.
+     * @return max size as integer. If no max size is set then it will default to 54.
      */
     public static int getMaxVaultSize(Player player) {
         if (player == null) {
@@ -73,6 +72,7 @@ public class VaultOperations {
      *
      * @param player The player to open to.
      * @param arg The vault number to open.
+     *
      * @return Whether or not the player was allowed to open it.
      */
     public static boolean openOwnVault(Player player, String arg) {
@@ -107,6 +107,7 @@ public class VaultOperations {
      * @param player The player to open to.
      * @param holder The user to whom the requested vault belongs.
      * @param arg The vault number to open.
+     *
      * @return Whether or not the player was allowed to open it.
      */
     public static boolean openOtherVault(Player player, String holder, String arg) {

src/main/java/com/drtshock/playervaults/vaultmanagement/VaultViewInfo.java

@@ -17,8 +17,7 @@
 package com.drtshock.playervaults.vaultmanagement;
 
 /**
- * A class that stores information about a vault viewing including the holder of
+ * A class that stores information about a vault viewing including the holder of the vault, and the vault number.
- * the vault, and the vault number.
  */
 public class VaultViewInfo {
 

src/main/java/org/json/JSONArray.java

@@ -34,47 +34,30 @@ import java.util.Iterator;
 import java.util.Map;
 
 /**
- * A JSONArray is an ordered sequence of values. Its external text form is a
+ * A JSONArray is an ordered sequence of values. Its external text form is a string wrapped in square brackets with
- * string wrapped in square brackets with commas separating the values. The
+ * commas separating the values. The internal form is an object having <code>get</code> and <code>opt</code> methods for
- * internal form is an object having <code>get</code> and <code>opt</code>
+ * accessing the values by index, and <code>put</code> methods for adding or replacing values. The values can be any of
- * methods for accessing the values by index, and <code>put</code> methods for
+ * these types: <code>Boolean</code>, <code>JSONArray</code>, <code>JSONObject</code>, <code>Number</code>,
- * adding or replacing values. The values can be any of these types:
+ * <code>String</code>, or the <code>JSONObject.NULL object</code>.
- * <code>Boolean</code>, <code>JSONArray</code>, <code>JSONObject</code>,
+ * <p/>
- * <code>Number</code>, <code>String</code>, or the
+ * The constructor can convert a JSON text into a Java object. The <code>toString</code> method converts to JSON text.
- * <code>JSONObject.NULL object</code>.
+ * <p/>
- * <p>
+ * A <code>get</code> method returns a value if one can be found, and throws an exception if one cannot be found. An
- * The constructor can convert a JSON text into a Java object. The
+ * <code>opt</code> method returns a default value instead of throwing an exception, and so is useful for obtaining
- * <code>toString</code> method converts to JSON text.
+ * optional values.
- * <p>
+ * <p/>
- * A <code>get</code> method returns a value if one can be found, and throws an
+ * The generic <code>get()</code> and <code>opt()</code> methods return an object which you can cast or query for type.
- * exception if one cannot be found. An <code>opt</code> method returns a
+ * There are also typed <code>get</code> and <code>opt</code> methods that do type checking and type coercion for you.
- * default value instead of throwing an exception, and so is useful for
+ * <p/>
- * obtaining optional values.
+ * The texts produced by the <code>toString</code> methods strictly conform to JSON syntax rules. The constructors are
- * <p>
+ * more forgiving in the texts they will accept: <ul> <li>An extra <code>,</code>&nbsp;<small>(comma)</small> may appear
- * The generic <code>get()</code> and <code>opt()</code> methods return an
+ * just before the closing bracket.</li> <li>The <code>null</code> value will be inserted when there is <code>,</code>
- * object which you can cast or query for type. There are also typed
+ * &nbsp;<small>(comma)</small> elision.</li> <li>Strings may be quoted with <code>'</code>&nbsp;<small>(single
- * <code>get</code> and <code>opt</code> methods that do type checking and type
+ * quote)</small>.</li> <li>Strings do not need to be quoted at all if they do not begin with a quote or single quote,
- * coercion for you.
+ * and if they do not contain leading or trailing spaces, and if they do not contain any of these characters: <code>{ }
- * <p>
+ * [ ] / \ : , = ; #</code> and if they do not look like numbers and if they are not the reserved words
- * The texts produced by the <code>toString</code> methods strictly conform to
+ * <code>true</code>, <code>false</code>, or <code>null</code>.</li> <li>Values can be separated by <code>;</code>
- * JSON syntax rules. The constructors are more forgiving in the texts they will
+ * <small>(semicolon)</small> as well as by <code>,</code> <small>(comma)</small>.</li> </ul>
- * accept:
- * <ul>
- * <li>An extra <code>,</code>&nbsp;<small>(comma)</small> may appear just
- * before the closing bracket.</li>
- * <li>The <code>null</code> value will be inserted when there is <code>,</code>
- * &nbsp;<small>(comma)</small> elision.</li>
- * <li>Strings may be quoted with <code>'</code>&nbsp;<small>(single
- * quote)</small>.</li>
- * <li>Strings do not need to be quoted at all if they do not begin with a quote
- * or single quote, and if they do not contain leading or trailing spaces, and
- * if they do not contain any of these characters:
- * <code>{ } [ ] / \ : , = ; #</code> and if they do not look like numbers and
- * if they are not the reserved words <code>true</code>, <code>false</code>, or
- * <code>null</code>.</li>
- * <li>Values can be separated by <code>;</code> <small>(semicolon)</small> as
- * well as by <code>,</code> <small>(comma)</small>.</li>
- * </ul>
  *
  * @author JSON.org
  * @version 2012-11-13
@@ -95,7 +78,9 @@ public class JSONArray {
 
     /**
      * Construct a JSONArray from a JSONTokener.
+     *
      * @param x A JSONTokener
+     *
      * @throws JSONException If there is a syntax error.
      */
     public JSONArray(JSONTokener x) throws JSONException {
@@ -132,9 +117,10 @@ public class JSONArray {
 
     /**
      * Construct a JSONArray from a source JSON text.
-     * @param source     A string that begins with
+     *
-     * <code>[</code>&nbsp;<small>(left bracket)</small>
+     * @param source A string that begins with <code>[</code>&nbsp;<small>(left bracket)</small> and ends with
-     *  and ends with <code>]</code>&nbsp;<small>(right bracket)</small>.
+     * <code>]</code>&nbsp;<small>(right bracket)</small>.
+     *
      * @throws JSONException If there is a syntax error.
      */
     public JSONArray(String source) throws JSONException {
@@ -143,6 +129,7 @@ public class JSONArray {
 
     /**
      * Construct a JSONArray from a Collection.
+     *
      * @param collection A Collection.
      */
     public JSONArray(Collection<?> collection) {
@@ -157,6 +144,7 @@ public class JSONArray {
 
     /**
      * Construct a JSONArray from an array
+     *
      * @throws JSONException If not an array.
      */
     public JSONArray(Object array) throws JSONException {
@@ -174,9 +162,11 @@ public class JSONArray {
 
     /**
      * Get the object value associated with an index.
-     * @param index
+     *
-     *  The index must be between 0 and length() - 1.
+     * @param index The index must be between 0 and length() - 1.
+     *
      * @return An object value.
+     *
      * @throws JSONException If there is no value for the index.
      */
     public Object get(int index) throws JSONException {
@@ -188,13 +178,13 @@ public class JSONArray {
     }
 
     /**
-     * Get the boolean value associated with an index.
+     * Get the boolean value associated with an index. The string values "true" and "false" are converted to boolean.
-     * The string values "true" and "false" are converted to boolean.
      *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return The truth.
-     * @throws JSONException If there is no value for the index or if the
+     *
-     *  value is not convertible to boolean.
+     * @throws JSONException If there is no value for the index or if the value is not convertible to boolean.
      */
     public boolean getBoolean(int index) throws JSONException {
         Object object = this.get(index);
@@ -214,9 +204,10 @@ public class JSONArray {
      * Get the double value associated with an index.
      *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return The value.
-     * @throws JSONException If the key is not found or if the value cannot
+     *
-     *  be converted to a number.
+     * @throws JSONException If the key is not found or if the value cannot be converted to a number.
      */
     public double getDouble(int index) throws JSONException {
         Object object = this.get(index);
@@ -234,7 +225,9 @@ public class JSONArray {
      * Get the int value associated with an index.
      *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return The value.
+     *
      * @throws JSONException If the key is not found or if the value is not a number.
      */
     public int getInt(int index) throws JSONException {
@@ -251,10 +244,12 @@ public class JSONArray {
 
     /**
      * Get the JSONArray associated with an index.
+     *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return A JSONArray value.
-     * @throws JSONException If there is no value for the index. or if the
+     *
-     * value is not a JSONArray
+     * @throws JSONException If there is no value for the index. or if the value is not a JSONArray
      */
     public JSONArray getJSONArray(int index) throws JSONException {
         Object object = this.get(index);
@@ -267,10 +262,12 @@ public class JSONArray {
 
     /**
      * Get the JSONObject associated with an index.
+     *
      * @param index subscript
+     *
      * @return A JSONObject value.
-     * @throws JSONException If there is no value for the index or if the
+     *
-     * value is not a JSONObject
+     * @throws JSONException If there is no value for the index or if the value is not a JSONObject
      */
     public JSONObject getJSONObject(int index) throws JSONException {
         Object object = this.get(index);
@@ -285,9 +282,10 @@ public class JSONArray {
      * Get the long value associated with an index.
      *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return The value.
-     * @throws JSONException If the key is not found or if the value cannot
+     *
-     *  be converted to a number.
+     * @throws JSONException If the key is not found or if the value cannot be converted to a number.
      */
     public long getLong(int index) throws JSONException {
         Object object = this.get(index);
@@ -303,8 +301,11 @@ public class JSONArray {
 
     /**
      * Get the string associated with an index.
+     *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return A string value.
+     *
      * @throws JSONException If there is no string value for the index.
      */
     public String getString(int index) throws JSONException {
@@ -317,7 +318,9 @@ public class JSONArray {
 
     /**
      * Determine if the value is null.
+     *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return true if the value at the index is null, or if there is no value.
      */
     public boolean isNull(int index) {
@@ -325,11 +328,13 @@ public class JSONArray {
     }
 
     /**
-     * Make a string from the contents of this JSONArray. The
+     * Make a string from the contents of this JSONArray. The <code>separator</code> string is inserted between each
-     * <code>separator</code> string is inserted between each element.
+     * element. Warning: This method assumes that the data structure is acyclical.
-     * Warning: This method assumes that the data structure is acyclical.
+     *
      * @param separator A string that will be inserted between the elements.
+     *
      * @return a string.
+     *
      * @throws JSONException If the array contains an invalid number.
      */
     public String join(String separator) throws JSONException {
@@ -356,9 +361,10 @@ public class JSONArray {
 
     /**
      * Get the optional object value associated with an index.
+     *
      * @param index The index must be between 0 and length() - 1.
-     * @return An object value, or null if there is no
+     *
-     *              object at that index.
+     * @return An object value, or null if there is no object at that index.
      */
     public Object opt(int index) {
         return (index < 0 || index >= this.length())
@@ -367,11 +373,11 @@ public class JSONArray {
     }
 
     /**
-     * Get the optional boolean value associated with an index.
+     * Get the optional boolean value associated with an index. It returns false if there is no value at that index, or
-     * It returns false if there is no value at that index,
+     * if the value is not Boolean.TRUE or the String "true".
-     * or if the value is not Boolean.TRUE or the String "true".
      *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return The truth.
      */
     public boolean optBoolean(int index) {
@@ -379,12 +385,12 @@ public class JSONArray {
     }
 
     /**
-     * Get the optional boolean value associated with an index.
+     * Get the optional boolean value associated with an index. It returns the defaultValue if there is no value at that
-     * It returns the defaultValue if there is no value at that index or if
+     * index or if it is not a Boolean or the String "true" or "false" (case insensitive).
-     * it is not a Boolean or the String "true" or "false" (case insensitive).
      *
      * @param index The index must be between 0 and length() - 1.
      * @param defaultValue A boolean default.
+     *
      * @return The truth.
      */
     public boolean optBoolean(int index, boolean defaultValue) {
@@ -396,11 +402,11 @@ public class JSONArray {
     }
 
     /**
-     * Get the optional double value associated with an index.
+     * Get the optional double value associated with an index. NaN is returned if there is no value for the index, or if
-     * NaN is returned if there is no value for the index,
+     * the value is not a number and cannot be converted to a number.
-     * or if the value is not a number and cannot be converted to a number.
      *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return The value.
      */
     public double optDouble(int index) {
@@ -408,12 +414,12 @@ public class JSONArray {
     }
 
     /**
-     * Get the optional double value associated with an index.
+     * Get the optional double value associated with an index. The defaultValue is returned if there is no value for the
-     * The defaultValue is returned if there is no value for the index,
+     * index, or if the value is not a number and cannot be converted to a number.
-     * or if the value is not a number and cannot be converted to a number.
      *
      * @param index subscript
      * @param defaultValue The default value.
+     *
      * @return The value.
      */
     public double optDouble(int index, double defaultValue) {
@@ -425,11 +431,11 @@ public class JSONArray {
     }
 
     /**
-     * Get the optional int value associated with an index.
+     * Get the optional int value associated with an index. Zero is returned if there is no value for the index, or if
-     * Zero is returned if there is no value for the index,
+     * the value is not a number and cannot be converted to a number.
-     * or if the value is not a number and cannot be converted to a number.
      *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return The value.
      */
     public int optInt(int index) {
@@ -437,11 +443,12 @@ public class JSONArray {
     }
 
     /**
-     * Get the optional int value associated with an index.
+     * Get the optional int value associated with an index. The defaultValue is returned if there is no value for the
-     * The defaultValue is returned if there is no value for the index,
+     * index, or if the value is not a number and cannot be converted to a number.
-     * or if the value is not a number and cannot be converted to a number.
+     *
      * @param index The index must be between 0 and length() - 1.
      * @param defaultValue The default value.
+     *
      * @return The value.
      */
     public int optInt(int index, int defaultValue) {
@@ -454,9 +461,10 @@ public class JSONArray {
 
     /**
      * Get the optional JSONArray associated with an index.
+     *
      * @param index subscript
-     * @return A JSONArray value, or null if the index has no value,
+     *
-     * or if the value is not a JSONArray.
+     * @return A JSONArray value, or null if the index has no value, or if the value is not a JSONArray.
      */
     public JSONArray optJSONArray(int index) {
         Object o = this.opt(index);
@@ -464,11 +472,11 @@ public class JSONArray {
     }
 
     /**
-     * Get the optional JSONObject associated with an index.
+     * Get the optional JSONObject associated with an index. Null is returned if the key is not found, or null if the
-     * Null is returned if the key is not found, or null if the index has
+     * index has no value, or if the value is not a JSONObject.
-     * no value, or if the value is not a JSONObject.
      *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return A JSONObject value.
      */
     public JSONObject optJSONObject(int index) {
@@ -477,11 +485,11 @@ public class JSONArray {
     }
 
     /**
-     * Get the optional long value associated with an index.
+     * Get the optional long value associated with an index. Zero is returned if there is no value for the index, or if
-     * Zero is returned if there is no value for the index,
+     * the value is not a number and cannot be converted to a number.
-     * or if the value is not a number and cannot be converted to a number.
      *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return The value.
      */
     public long optLong(int index) {
@@ -489,11 +497,12 @@ public class JSONArray {
     }
 
     /**
-     * Get the optional long value associated with an index.
+     * Get the optional long value associated with an index. The defaultValue is returned if there is no value for the
-     * The defaultValue is returned if there is no value for the index,
+     * index, or if the value is not a number and cannot be converted to a number.
-     * or if the value is not a number and cannot be converted to a number.
+     *
      * @param index The index must be between 0 and length() - 1.
      * @param defaultValue The default value.
+     *
      * @return The value.
      */
     public long optLong(int index, long defaultValue) {
@@ -505,11 +514,11 @@ public class JSONArray {
     }
 
     /**
-     * Get the optional string value associated with an index. It returns an
+     * Get the optional string value associated with an index. It returns an empty string if there is no value at that
-     * empty string if there is no value at that index. If the value
+     * index. If the value is not a string and is not null, then it is coverted to a string.
-     * is not a string and is not null, then it is coverted to a string.
      *
      * @param index The index must be between 0 and length() - 1.
+     *
      * @return A String value.
      */
     public String optString(int index) {
@@ -517,11 +526,11 @@ public class JSONArray {
     }
 
     /**
-     * Get the optional string associated with an index.
+     * Get the optional string associated with an index. The defaultValue is returned if the key is not found.
-     * The defaultValue is returned if the key is not found.
      *
      * @param index The index must be between 0 and length() - 1.
      * @param defaultValue The default value.
+     *
      * @return A String value.
      */
     public String optString(int index, String defaultValue) {
@@ -535,6 +544,7 @@ public class JSONArray {
      * Append a boolean value. This increases the array's length by one.
      *
      * @param value A boolean value.
+     *
      * @return this.
      */
     public JSONArray put(boolean value) {
@@ -543,9 +553,10 @@ public class JSONArray {
     }
 
     /**
-     * Put a value in the JSONArray, where the value will be a
+     * Put a value in the JSONArray, where the value will be a JSONArray which is produced from a Collection.
-     * JSONArray which is produced from a Collection.
+     *
      * @param value A Collection value.
+     *
      * @return this.
      */
     public JSONArray put(Collection<?> value) {
@@ -557,8 +568,10 @@ public class JSONArray {
      * Append a double value. This increases the array's length by one.
      *
      * @param value A double value.
-     * @throws JSONException if the value is not finite.
+     *
      * @return this.
+     *
+     * @throws JSONException if the value is not finite.
      */
     public JSONArray put(double value) throws JSONException {
         Double d = new Double(value);
@@ -571,6 +584,7 @@ public class JSONArray {
      * Append an int value. This increases the array's length by one.
      *
      * @param value An int value.
+     *
      * @return this.
      */
     public JSONArray put(int value) {
@@ -582,6 +596,7 @@ public class JSONArray {
      * Append an long value. This increases the array's length by one.
      *
      * @param value A long value.
+     *
      * @return this.
      */
     public JSONArray put(long value) {
@@ -590,9 +605,10 @@ public class JSONArray {
     }
 
     /**
-     * Put a value in the JSONArray, where the value will be a
+     * Put a value in the JSONArray, where the value will be a JSONObject which is produced from a Map.
-     * JSONObject which is produced from a Map.
+     *
      * @param value A Map value.
+     *
      * @return this.
      */
     public JSONArray put(Map<?, ?> value) {
@@ -602,9 +618,10 @@ public class JSONArray {
 
     /**
      * Append an object value. This increases the array's length by one.
-     * @param value An object value.  The value should be a
+     *
-     *  Boolean, Double, Integer, JSONArray, JSONObject, Long, or String, or the
+     * @param value An object value.  The value should be a Boolean, Double, Integer, JSONArray, JSONObject, Long, or
-     *  JSONObject.NULL object.
+     * String, or the JSONObject.NULL object.
+     *
      * @return this.
      */
     public JSONArray put(Object value) {
@@ -613,12 +630,14 @@ public class JSONArray {
     }
 
     /**
-     * Put or replace a boolean value in the JSONArray. If the index is greater
+     * Put or replace a boolean value in the JSONArray. If the index is greater than the length of the JSONArray, then
-     * than the length of the JSONArray, then null elements will be added as
+     * null elements will be added as necessary to pad it out.
-     * necessary to pad it out.
+     *
      * @param index The subscript.
      * @param value A boolean value.
+     *
      * @return this.
+     *
      * @throws JSONException If the index is negative.
      */
     public JSONArray put(int index, boolean value) throws JSONException {
@@ -627,13 +646,14 @@ public class JSONArray {
     }
 
     /**
-     * Put a value in the JSONArray, where the value will be a
+     * Put a value in the JSONArray, where the value will be a JSONArray which is produced from a Collection.
-     * JSONArray which is produced from a Collection.
+     *
      * @param index The subscript.
      * @param value A Collection value.
+     *
      * @return this.
-     * @throws JSONException If the index is negative or if the value is
+     *
-     * not finite.
+     * @throws JSONException If the index is negative or if the value is not finite.
      */
     public JSONArray put(int index, Collection<?> value) throws JSONException {
         this.put(index, new JSONArray(value));
@@ -641,14 +661,15 @@ public class JSONArray {
     }
 
     /**
-     * Put or replace a double value. If the index is greater than the length of
+     * Put or replace a double value. If the index is greater than the length of the JSONArray, then null elements will
-     *  the JSONArray, then null elements will be added as necessary to pad
+     * be added as necessary to pad it out.
-     *  it out.
+     *
      * @param index The subscript.
      * @param value A double value.
+     *
      * @return this.
-     * @throws JSONException If the index is negative or if the value is
+     *
-     * not finite.
+     * @throws JSONException If the index is negative or if the value is not finite.
      */
     public JSONArray put(int index, double value) throws JSONException {
         this.put(index, new Double(value));
@@ -656,12 +677,14 @@ public class JSONArray {
     }
 
     /**
-     * Put or replace an int value. If the index is greater than the length of
+     * Put or replace an int value. If the index is greater than the length of the JSONArray, then null elements will be
-     *  the JSONArray, then null elements will be added as necessary to pad
+     * added as necessary to pad it out.
-     *  it out.
+     *
      * @param index The subscript.
      * @param value An int value.
+     *
      * @return this.
+     *
      * @throws JSONException If the index is negative.
      */
     public JSONArray put(int index, int value) throws JSONException {
@@ -670,12 +693,14 @@ public class JSONArray {
     }
 
     /**
-     * Put or replace a long value. If the index is greater than the length of
+     * Put or replace a long value. If the index is greater than the length of the JSONArray, then null elements will be
-     *  the JSONArray, then null elements will be added as necessary to pad
+     * added as necessary to pad it out.
-     *  it out.
+     *
      * @param index The subscript.
      * @param value A long value.
+     *
      * @return this.
+     *
      * @throws JSONException If the index is negative.
      */
     public JSONArray put(int index, long value) throws JSONException {
@@ -684,13 +709,14 @@ public class JSONArray {
     }
 
     /**
-     * Put a value in the JSONArray, where the value will be a
+     * Put a value in the JSONArray, where the value will be a JSONObject that is produced from a Map.
-     * JSONObject that is produced from a Map.
+     *
      * @param index The subscript.
      * @param value The Map value.
+     *
      * @return this.
-     * @throws JSONException If the index is negative or if the the value is
+     *
-     *  an invalid number.
+     * @throws JSONException If the index is negative or if the the value is an invalid number.
      */
     public JSONArray put(int index, Map<?, ?> value) throws JSONException {
         this.put(index, new JSONObject(value));
@@ -698,16 +724,16 @@ public class JSONArray {
     }
 
     /**
-     * Put or replace an object value in the JSONArray. If the index is greater
+     * Put or replace an object value in the JSONArray. If the index is greater than the length of the JSONArray, then
-     *  than the length of the JSONArray, then null elements will be added as
+     * null elements will be added as necessary to pad it out.
-     *  necessary to pad it out.
+     *
      * @param index The subscript.
-     * @param value The value to put into the array. The value should be a
+     * @param value The value to put into the array. The value should be a Boolean, Double, Integer, JSONArray,
-     *  Boolean, Double, Integer, JSONArray, JSONObject, Long, or String, or the
+     * JSONObject, Long, or String, or the JSONObject.NULL object.
-     *  JSONObject.NULL object.
+     *
      * @return this.
-     * @throws JSONException If the index is negative or if the the value is
+     *
-     *  an invalid number.
+     * @throws JSONException If the index is negative or if the the value is an invalid number.
      */
     public JSONArray put(int index, Object value) throws JSONException {
         JSONObject.testValidity(value);
@@ -727,9 +753,10 @@ public class JSONArray {
 
     /**
      * Remove an index and close the hole.
+     *
      * @param index The index of the element to be removed.
-     * @return The value that was associated with the index,
+     *
-     * or null if there was no value.
+     * @return The value that was associated with the index, or null if there was no value.
      */
     public Object remove(int index) {
         Object o = this.opt(index);
@@ -738,12 +765,12 @@ public class JSONArray {
     }
 
     /**
-     * Produce a JSONObject by combining a JSONArray of names with the values
+     * Produce a JSONObject by combining a JSONArray of names with the values of this JSONArray.
-     * of this JSONArray.
+     *
-     * @param names A JSONArray containing a list of key strings. These will be
+     * @param names A JSONArray containing a list of key strings. These will be paired with the values.
-     * paired with the values.
+     *
-     * @return A JSONObject, or null if there are no names or if this JSONArray
+     * @return A JSONObject, or null if there are no names or if this JSONArray has no values.
-     * has no values.
+     *
      * @throws JSONException If any of the names are null.
      */
     public JSONObject toJSONObject(JSONArray names) throws JSONException {
@@ -758,15 +785,13 @@ public class JSONArray {
     }
 
     /**
-     * Make a JSON text of this JSONArray. For compactness, no
+     * Make a JSON text of this JSONArray. For compactness, no unnecessary whitespace is added. If it is not possible to
-     * unnecessary whitespace is added. If it is not possible to produce a
+     * produce a syntactically correct JSON text then null will be returned instead. This could occur if the array
-     * syntactically correct JSON text then null will be returned instead. This
+     * contains an invalid number.
-     * could occur if the array contains an invalid number.
+     * <p/>
-     * <p>
      * Warning: This method assumes that the data structure is acyclical.
      *
-     * @return a printable, displayable, transmittable
+     * @return a printable, displayable, transmittable representation of the array.
-     *  representation of the array.
      */
     public String toString() {
         try {
@@ -777,14 +802,15 @@ public class JSONArray {
     }
 
     /**
-     * Make a prettyprinted JSON text of this JSONArray.
+     * Make a prettyprinted JSON text of this JSONArray. Warning: This method assumes that the data structure is
-     * Warning: This method assumes that the data structure is acyclical.
+     * acyclical.
-     * @param indentFactor The number of spaces to add to each level of
+     *
-     *  indentation.
+     * @param indentFactor The number of spaces to add to each level of indentation.
-     * @return a printable, displayable, transmittable
+     *
-     *  representation of the object, beginning
+     * @return a printable, displayable, transmittable representation of the object, beginning with
-     *  with <code>[</code>&nbsp;<small>(left bracket)</small> and ending
+     * <code>[</code>&nbsp;<small>(left bracket)</small> and ending with <code>]</code>&nbsp;<small>(right
-     *  with <code>]</code>&nbsp;<small>(right bracket)</small>.
+     * bracket)</small>.
+     *
      * @throws JSONException
      */
     public String toString(int indentFactor) throws JSONException {
@@ -795,12 +821,12 @@ public class JSONArray {
     }
 
     /**
-     * Write the contents of the JSONArray as JSON text to a writer. For
+     * Write the contents of the JSONArray as JSON text to a writer. For compactness, no whitespace is added.
-     * compactness, no whitespace is added.
+     * <p/>
-     * <p>
      * Warning: This method assumes that the data structure is acyclical.
      *
      * @return The writer.
+     *
      * @throws JSONException
      */
     public Writer write(Writer writer) throws JSONException {
@@ -808,16 +834,15 @@ public class JSONArray {
     }
 
     /**
-     * Write the contents of the JSONArray as JSON text to a writer. For
+     * Write the contents of the JSONArray as JSON text to a writer. For compactness, no whitespace is added.
-     * compactness, no whitespace is added.
+     * <p/>
-     * <p>
      * Warning: This method assumes that the data structure is acyclical.
      *
-     * @param indentFactor
+     * @param indentFactor The number of spaces to add to each level of indentation.
-     *            The number of spaces to add to each level of indentation.
+     * @param indent The indention of the top level.
-     * @param indent
+     *
-     *            The indention of the top level.
      * @return The writer.
+     *
      * @throws JSONException
      */
     Writer write(Writer writer, int indentFactor, int indent)

src/main/java/org/json/JSONException.java

@@ -2,6 +2,7 @@ package org.json;
 
 /**
  * The JSONException is thrown by the JSON.org classes when things are amiss.
+ *
  * @author JSON.org
  * @version 2010-12-24
  */
@@ -12,6 +13,7 @@ public class JSONException extends Exception {
 
     /**
      * Constructs a JSONException with an explanatory message.
+     *
      * @param message Detail about the reason for the exception.
      */
     public JSONException(String message) {

src/main/java/org/json/JSONString.java

@@ -1,18 +1,15 @@
 package org.json;
 
 /**
- * The <code>JSONString</code> interface allows a <code>toJSONString()</code>
+ * The <code>JSONString</code> interface allows a <code>toJSONString()</code> method so that a class can change the
- * method so that a class can change the behavior of
+ * behavior of <code>JSONObject.toString()</code>, <code>JSONArray.toString()</code>, and
- * <code>JSONObject.toString()</code>, <code>JSONArray.toString()</code>,
+ * <code>JSONWriter.value(</code>Object<code>)</code>. The <code>toJSONString</code> method will be used instead of the
- * and <code>JSONWriter.value(</code>Object<code>)</code>. The
+ * default behavior of using the Object's <code>toString()</code> method and quoting the result.
- * <code>toJSONString</code> method will be used instead of the default behavior
- * of using the Object's <code>toString()</code> method and quoting the result.
  */
 public interface JSONString {
 
     /**
-     * The <code>toJSONString</code> method allows a class to produce its own JSON
+     * The <code>toJSONString</code> method allows a class to produce its own JSON serialization.
-     * serialization.
      *
      * @return A strictly syntactically correct JSON text.
      */

src/main/java/org/json/JSONTokener.java

@@ -1,11 +1,6 @@
 package org.json;
 
-import java.io.BufferedReader;
+import java.io.*;
-import java.io.IOException;
-import java.io.InputStream;
-import java.io.InputStreamReader;
-import java.io.Reader;
-import java.io.StringReader;
 
 /*
  * Copyright (c) 2002 JSON.org
@@ -32,9 +27,9 @@ import java.io.StringReader;
  */
 
 /**
- * A JSONTokener takes a source string and extracts characters and tokens from
+ * A JSONTokener takes a source string and extracts characters and tokens from it. It is used by the JSONObject and
- * it. It is used by the JSONObject and JSONArray constructors to parse
+ * JSONArray constructors to parse JSON source strings.
- * JSON source strings.
+ *
  * @author JSON.org
  * @version 2012-02-16
  */
@@ -82,9 +77,8 @@ public class JSONTokener {
     }
 
     /**
-     * Back up one character. This provides a sort of lookahead capability,
+     * Back up one character. This provides a sort of lookahead capability, so that you can test for a digit or letter
-     * so that you can test for a digit or letter before attempting to parse
+     * before attempting to parse the next number or identifier.
-     * the next number or identifier.
      */
     public void back() throws JSONException {
         if (this.usePrevious || this.index <= 0) {
@@ -98,8 +92,9 @@ public class JSONTokener {
 
     /**
      * Get the hex value of a character (base16).
-     * @param c A character between '0' and '9' or between 'A' and 'F' or
+     *
-     * between 'a' and 'f'.
+     * @param c A character between '0' and '9' or between 'A' and 'F' or between 'a' and 'f'.
+     *
      * @return An int between 0 and 15, or -1 if c was not a hex digit.
      */
     public static int dehexchar(char c) {
@@ -120,8 +115,8 @@ public class JSONTokener {
     }
 
     /**
-     * Determine if the source string still contains characters that next()
+     * Determine if the source string still contains characters that next() can consume.
-     * can consume.
+     *
      * @return true if not yet at the end of the source.
      */
     public boolean more() throws JSONException {
@@ -170,10 +165,12 @@ public class JSONTokener {
     }
 
     /**
-     * Consume the next character, and check that it matches a specified
+     * Consume the next character, and check that it matches a specified character.
-     * character.
+     *
      * @param c The character to match.
+     *
      * @return The character.
+     *
      * @throws JSONException if the character does not match.
      */
     public char next(char c) throws JSONException {
@@ -189,10 +186,10 @@ public class JSONTokener {
      * Get the next n characters.
      *
      * @param n The number of characters to take.
+     *
      * @return A string of n characters.
-     * @throws JSONException
+     *
-     *   Substring bounds error if there are not
+     * @throws JSONException Substring bounds error if there are not n characters remaining in the source string.
-     *   n characters remaining in the source string.
      */
     public String next(int n) throws JSONException {
         if (n == 0) {
@@ -214,8 +211,10 @@ public class JSONTokener {
 
     /**
      * Get the next char in the string, skipping whitespace.
-     * @throws JSONException
+     *
      * @return A character, or 0 if there are no more characters.
+     *
+     * @throws JSONException
      */
     public char nextClean() throws JSONException {
         for (; ; ) {
@@ -227,14 +226,14 @@ public class JSONTokener {
     }
 
     /**
-     * Return the characters up to the next close quote character.
+     * Return the characters up to the next close quote character. Backslash processing is done. The formal JSON format
-     * Backslash processing is done. The formal JSON format does not
+     * does not allow strings in single quotes, but an implementation is allowed to accept them.
-     * allow strings in single quotes, but an implementation is allowed to
+     *
-     * accept them.
+     * @param quote The quoting character, either <code>"</code>&nbsp;<small>(double quote)</small> or
-     * @param quote The quoting character, either
-     *      <code>"</code>&nbsp;<small>(double quote)</small> or
      * <code>'</code>&nbsp;<small>(single quote)</small>.
+     *
      * @return A String.
+     *
      * @throws JSONException Unterminated string.
      */
     public String nextString(char quote) throws JSONException {
@@ -288,9 +287,10 @@ public class JSONTokener {
     }
 
     /**
-     * Get the text up but not including the specified character or the
+     * Get the text up but not including the specified character or the end of line, whichever comes first.
-     * end of line, whichever comes first.
+     *
      * @param delimiter A delimiter character.
+     *
      * @return A string.
      */
     public String nextTo(char delimiter) throws JSONException {
@@ -308,9 +308,11 @@ public class JSONTokener {
     }
 
     /**
-     * Get the text up but not including one of the specified delimiter
+     * Get the text up but not including one of the specified delimiter characters or the end of line, whichever comes
-     * characters or the end of line, whichever comes first.
+     * first.
+     *
      * @param delimiters A set of delimiter characters.
+     *
      * @return A string, trimmed.
      */
     public String nextTo(String delimiters) throws JSONException {
@@ -330,11 +332,12 @@ public class JSONTokener {
     }
 
     /**
-     * Get the next value. The value can be a Boolean, Double, Integer,
+     * Get the next value. The value can be a Boolean, Double, Integer, JSONArray, JSONObject, Long, or String, or the
-     * JSONArray, JSONObject, Long, or String, or the JSONObject.NULL object.
+     * JSONObject.NULL object.
-     * @throws JSONException If syntax error.
      *
      * @return An object.
+     *
+     * @throws JSONException If syntax error.
      */
     public Object nextValue() throws JSONException {
         char c = this.nextClean();
@@ -376,11 +379,12 @@ public class JSONTokener {
     }
 
     /**
-     * Skip characters until the next character is the requested character.
+     * Skip characters until the next character is the requested character. If the requested character is not found, no
-     * If the requested character is not found, no characters are skipped.
+     * characters are skipped.
+     *
      * @param to A character to skip to.
-     * @return The requested character, or zero if the requested character
+     *
-     * is not found.
+     * @return The requested character, or zero if the requested character is not found.
      */
     public char skipTo(char to) throws JSONException {
         char c;
@@ -411,6 +415,7 @@ public class JSONTokener {
      * Make a JSONException to signal a syntax error.
      *
      * @param message The error message.
+     *
      * @return A JSONException object, suitable for throwing
      */
     public JSONException syntaxError(String message) {