fix javadoc errors

twitter4j-async/src/main/java/twitter4j/api/SpamReportingResourceAsync.java

@@ -22,7 +22,7 @@
 
 /**
  * Not yet supported.
- * <p/>
+ * <p>
  * http://yusuke.homeip.net/jira/browse/TFJ-223
  */
 public interface SpamReportingResourceAsync {

twitter4j-core/src/internal-http/java/twitter4j/HttpParameter.java

@@ -305,8 +305,9 @@ public static String decode(String value) {
 
     /**
      * Parses a query string without the leading "?"
-     * 
-     * @param queryParameters a query parameter string, like a=hello&b=world
+     *
+     * @param queryParameters a query parameter string, like a=hello&b=world
+     * @return decoded parameters
      */
     public static List<HttpParameter> decodeParameters(String queryParameters) {
         List<HttpParameter> result=new ArrayList<HttpParameter>();

twitter4j-core/src/internal-http/java/twitter4j/HttpResponse.java

@@ -56,7 +56,7 @@ public int getStatusCode() {
      * Returns the response stream.<br>
      * This method cannot be called after calling asString() or asDcoument()<br>
      * It is suggested to call disconnect() after consuming the stream.
-     * <p/>
+     * <p>
      * Disconnects the internal HttpURLConnection silently.
      *
      * @return response body stream
@@ -74,7 +74,7 @@ public InputStream asStream() {
      * Disconnects the internal HttpURLConnection silently.
      *
      * @return response body
-     * @throws TwitterException
+     * @throws TwitterException when there is any network issue upon response body consumption
      */
     public String asString() throws TwitterException {
         if (null == responseAsString) {
@@ -123,7 +123,7 @@ public String asString() throws TwitterException {
      * Disconnects the internal HttpURLConnection silently.
      *
      * @return response body as twitter4j.JSONObject
-     * @throws TwitterException
+     * @throws TwitterException when the response body is not in JSON Object format
      */
     public JSONObject asJSONObject() throws TwitterException {
         if (json == null) {
@@ -139,7 +139,7 @@ public JSONObject asJSONObject() throws TwitterException {
                     logger.debug(json.toString(1));
                 } else {
                     logger.debug(responseAsString != null ? responseAsString :
-                            json.toString());
+                        json.toString());
                 }
             } catch (JSONException jsone) {
                 if (responseAsString == null) {
@@ -167,7 +167,7 @@ public JSONObject asJSONObject() throws TwitterException {
      * Disconnects the internal HttpURLConnection silently.
      *
      * @return response body as twitter4j.JSONArray
-     * @throws TwitterException
+     * @throws TwitterException when the response body is not in JSON Array format
      */
     public JSONArray asJSONArray() throws TwitterException {
         if (jsonArray == null) {
@@ -183,7 +183,7 @@ public JSONArray asJSONArray() throws TwitterException {
                     logger.debug(jsonArray.toString(1));
                 } else {
                     logger.debug(responseAsString != null ? responseAsString :
-                            jsonArray.toString());
+                        jsonArray.toString());
                 }
             } catch (JSONException jsone) {
                 if (logger.isDebugEnabled()) {
@@ -224,10 +224,10 @@ private void disconnectForcibly() {
     @Override
     public String toString() {
         return "HttpResponse{" +
-                "statusCode=" + statusCode +
-                ", responseAsString='" + responseAsString + '\'' +
-                ", is=" + is +
-                ", streamConsumed=" + streamConsumed +
-                '}';
+            "statusCode=" + statusCode +
+            ", responseAsString='" + responseAsString + '\'' +
+            ", is=" + is +
+            ", streamConsumed=" + streamConsumed +
+            '}';
     }
 }

twitter4j-core/src/internal-http/java/twitter4j/StreamingGZIPInputStream.java

@@ -33,7 +33,7 @@ public StreamingGZIPInputStream(InputStream is) throws IOException {
      * Overrides behavior of GZIPInputStream which assumes we have all the data available
      * which is not true for streaming. We instead rely on the underlying stream to tell us
      * how much data is available.
-     * <p/>
+     * <p>
      * Programs should not count on this method to return the actual number
      * of bytes that could be read without blocking.
      *

twitter4j-core/src/internal-json/java/twitter4j/JSONArray.java

@@ -40,20 +40,20 @@ of this software and associated documentation files (the "Software"), to deal
  * {@code}Boolean{/code}, {@code}JSONArray{/code}, {@code}JSONObject{/code},
  * {@code}Number{/code}, {@code}String{/code}, or the
  * {@code}JSONObject.NULL object{/code}.
- * <p/>
+ * <p>
  * The constructor can convert a JSON text into a Java object. The
  * {@code}toString{/code} method converts to JSON text.
- * <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 {@code}opt{/code} method returns a
  * default value instead of throwing an exception, and so is useful for
  * obtaining optional values.
- * <p/>
+ * <p>
  * The generic {@code}get(){/code} and {@code}opt(){/code} methods return an
  * object which you can cast or query for type. There are also typed
  * {@code}get{/code} and {@code}opt{/code} methods that do type checking and type
  * coercion for you.
- * <p/>
+ * <p>
  * The texts produced by the {@code}toString{/code} methods strictly conform to
  * JSON syntax rules. The constructors are more forgiving in the texts they will
  * accept:
@@ -165,6 +165,7 @@ public JSONArray(Collection collection) {
     /**
      * Construct a JSONArray from an array
      *
+     * @param array array
      * @throws JSONException If not an array.
      */
     public JSONArray(Object array) throws JSONException {
@@ -594,7 +595,7 @@ public JSONArray put(int index, Object value) throws JSONException {
      * unnecessary whitespace is added. If it is not possible to produce a
      * syntactically correct JSON text then null will be returned instead. This
      * 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
@@ -619,7 +620,7 @@ public String toString() {
      * representation of the object, beginning
      * with {@code}[{/code}&nbsp;<small>(left bracket)</small> and ending
      * with {@code}]{/code}&nbsp;<small>(right bracket)</small>.
-     * @throws JSONException
+     * @throws JSONException when failed to stringify
      */
     public String toString(int indentFactor) throws JSONException {
         return toString(indentFactor, 0);
@@ -635,7 +636,7 @@ public String toString(int indentFactor) throws JSONException {
      * @param indent       The indention of the top level.
      * @return a printable, displayable, transmittable
      * representation of the array.
-     * @throws JSONException
+     * @throws JSONException when failed to stringify
      */
     String toString(int indentFactor, int indent) throws JSONException {
         int len = length();
@@ -673,11 +674,12 @@ String toString(int indentFactor, int indent) throws JSONException {
     /**
      * Write the contents of the JSONArray as JSON text to a writer.
      * For compactness, no whitespace is added.
-     * <p/>
+     * <p>
      * Warning: This method assumes that the data structure is acyclical.
      *
+     * @param writer writer
      * @return The writer.
-     * @throws JSONException
+     * @throws JSONException when failed to write the content
      */
     public Writer write(Writer writer) throws JSONException {
         try {

twitter4j-core/src/internal-json/java/twitter4j/JSONObject.java

@@ -47,17 +47,17 @@ of this software and associated documentation files (the "Software"), to deal
  * exception if one cannot be found. An {@code}opt{/code} method returns a
  * default value instead of throwing an exception, and so is useful for
  * obtaining optional values.
- * <p/>
+ * <p>
  * The generic {@code}get(){/code} and {@code}opt(){/code} methods return an
  * object, which you can cast or query for type. There are also typed
  * {@code}get{/code} and {@code}opt{/code} methods that do type checking and type
  * coercion for you. The opt methods differ from the get methods in that they
  * do not throw. Instead, they return a specified value, such as null.
- * <p/>
+ * <p>
  * The {@code}put{/code} methods add or replace values in an object. For example,
  * <pre>myString = new JSONObject().put("JSON", "Hello, World!").toString();</pre>
  * produces the string {@code}{"JSON": "Hello, World"}{/code}.
- * <p/>
+ * <p>
  * The texts produced by the {@code}toString{/code} methods strictly conform to
  * the JSON syntax rules.
  * The constructors are more forgiving in the texts they will accept:
@@ -72,7 +72,7 @@ of this software and associated documentation files (the "Software"), to deal
  * {@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>Keys can be followed by {@code}={/code} or {@code}=>{/code} as well as
+ * <li>Keys can be followed by {@code}={/code} or {@code}=&gt;{/code} as well as
  * by {@code}:{/code}.</li>
  * <li>Values can be followed by {@code};{/code} <small>(semicolon)</small> as
  * well as by {@code},{/code} <small>(comma)</small>.</li>
@@ -251,11 +251,11 @@ public JSONObject(Map map) {
      * with {@code}"get"{/code} or {@code}"is"{/code} followed by an uppercase letter,
      * the method is invoked, and a key and the value returned from the getter method
      * are put into the new JSONObject.
-     * <p/>
+     * <p>
      * The key is formed by removing the {@code}"get"{/code} or {@code}"is"{/code} prefix.
      * If the second remaining character is not upper case, then the first
      * character is converted to lower case.
-     * <p/>
+     * <p>
      * For example, if an object has a method named {@code}"getName"{/code}, and
      * if the result of calling {@code}object.getName(){/code} is {@code}"Larry Fine"{/code},
      * then the JSONObject will contain {@code}"name": "Larry Fine"{/code}.
@@ -666,16 +666,6 @@ public JSONObject put(String key, boolean value) throws JSONException {
         return this;
     }
 
-
-    /**
-     * Put a key/value pair in the JSONObject, where the value will be a
-     * JSONArray which is produced from a Collection.
-     *
-     * @param key   A key string.
-     * @param value A Collection value.
-     * @return this.
-     * @throws JSONException
-     */
     public JSONObject put(String key, Collection value) throws JSONException {
         put(key, new JSONArray(value));
         return this;
@@ -731,7 +721,7 @@ public JSONObject put(String key, long value) throws JSONException {
      * @param key   A key string.
      * @param value A Map value.
      * @return this.
-     * @throws JSONException
+     * @throws JSONException when failed to put value
      */
     public JSONObject put(String key, Map value) throws JSONException {
         put(key, new JSONObject(value));
@@ -807,7 +797,7 @@ public JSONObject putOpt(String key, Object value) throws JSONException {
 
     /**
      * Produce a string in double quotes with backslash sequences in all the
-     * right places. A backslash will be inserted within </, producing <\/,
+     * right places. A backslash will be inserted within &lt;/, producing &lt;\/,
      * allowing JSON text to be delivered in HTML. In JSON text, a string
      * cannot contain a control character or an unescaped quote or backslash.
      *
@@ -976,7 +966,7 @@ public static void testValidity(Object o) throws JSONException {
      * Make a JSON text of this JSONObject. For compactness, no whitespace
      * is added. If this would not result in a syntactically correct JSON text,
      * then null will be returned instead.
-     * <p/>
+     * <p>
      * Warning: This method assumes that the data structure is acyclical.
      *
      * @return a printable, displayable, portable, transmittable
@@ -1008,7 +998,7 @@ public String toString() {
 
     /**
      * Make a prettyprinted JSON text of this JSONObject.
-     * <p/>
+     * <p>
      * Warning: This method assumes that the data structure is acyclical.
      *
      * @param indentFactor The number of spaces to add to each level of
@@ -1026,7 +1016,7 @@ public String toString(int indentFactor) throws JSONException {
 
     /**
      * Make a prettyprinted JSON text of this JSONObject.
-     * <p/>
+     * <p>
      * Warning: This method assumes that the data structure is acyclical.
      *
      * @param indentFactor The number of spaces to add to each level of
@@ -1093,8 +1083,7 @@ String toString(int indentFactor, int indent) throws JSONException {
      * will be called. If the value is a MAP, then a JSONObject will be made
      * from it and its toJSONString method will be called. Otherwise, the
      * value's toString method will be called, and the result will be quoted.
-     * <p/>
-     * <p/>
+     * <p>
      * Warning: This method assumes that the data structure is acyclical.
      *
      * @param value The value to be serialized.
@@ -1130,7 +1119,7 @@ public static String valueToString(Object value) throws JSONException {
 
     /**
      * Make a prettyprinted JSON text of an object value.
-     * <p/>
+     * <p>
      * Warning: This method assumes that the data structure is acyclical.
      *
      * @param value        The value to be serialized.
@@ -1223,15 +1212,6 @@ public static Object wrap(Object object) {
     }
 
 
-    /**
-     * Write the contents of the JSONObject as JSON text to a writer.
-     * For compactness, no whitespace is added.
-     * <p/>
-     * Warning: This method assumes that the data structure is acyclical.
-     *
-     * @return The writer.
-     * @throws JSONException
-     */
     public Writer write(Writer writer) throws JSONException {
         try {
             boolean commanate = false;

twitter4j-core/src/internal-json/java/twitter4j/JSONTokener.java

@@ -64,6 +64,8 @@ public JSONTokener(Reader reader) {
 
     /**
      * Construct a JSONTokener from an InputStream.
+     * @param inputStream input stream
+     * @throws JSONException when failed to construct
      */
     public JSONTokener(InputStream inputStream) throws JSONException {
         this(new InputStreamReader(inputStream));
@@ -84,6 +86,7 @@ public JSONTokener(String s) {
      * Back up one character. This provides a sort of lookahead capability,
      * so that you can test for a digit or letter before attempting to parse
      * the next number or identifier.
+     * @throws JSONException when tried to back two steps
      */
     public void back() throws JSONException {
         if (usePrevious || index <= 0) {
@@ -106,6 +109,7 @@ public boolean end() {
      * can consume.
      *
      * @return true if not yet at the end of the source.
+     * @throws JSONException when failed to determine
      */
     public boolean more() throws JSONException {
         next();
@@ -121,6 +125,7 @@ public boolean more() throws JSONException {
      * Get the next character in the source string.
      *
      * @return The next character, or 0 if past the end of the source string.
+     * @throws JSONException when failed to read the next character from the reader
      */
     public char next() throws JSONException {
         int c;
@@ -203,7 +208,7 @@ public String next(int n) throws JSONException {
      * Get the next char in the string, skipping whitespace.
      *
      * @return A character, or 0 if there are no more characters.
-     * @throws JSONException
+     * @throws JSONException when failed to read the content from the reader
      */
     public char nextClean() throws JSONException {
         for (; ; ) {

twitter4j-core/src/internal-json/java/twitter4j/UserJSONImpl.java

@@ -103,11 +103,10 @@ private void init(JSONObject json) throws TwitterException {
 
             // descriptionUrlEntities <=> entities/descriptions/urls[]
             descriptionURLEntities = getURLEntitiesFromJSON(json, "description");
-            descriptionURLEntities = descriptionURLEntities == null ? new URLEntity[0] : descriptionURLEntities;
 
             // urlEntity <=> entities/url/urls[]
             URLEntity[] urlEntities = getURLEntitiesFromJSON(json, "url");
-            if (urlEntities != null && urlEntities.length > 0) {
+            if (urlEntities.length > 0) {
                 urlEntity = urlEntities[0];
             }
 
@@ -192,7 +191,7 @@ private static URLEntity[] getURLEntitiesFromJSON(JSONObject json, String catego
                 }
             }
         }
-        return null;
+        return new URLEntity[0];
     }
 
     @Override