Modified the javadoc for more readable.

(put the API URL in javadoc is like bring owls to Athens.)
qrtt1 · Mar 2, 2013 · 3cd80f8 · 3cd80f8
1 parent d4a1943
commit 3cd80f8
Show file tree

Hide file tree

Showing 4 changed files with 100 additions and 15 deletions.
diff --git a/src/main/java/com/google/jplurk_oauth/module/Alerts.java b/src/main/java/com/google/jplurk_oauth/module/Alerts.java
@@ -10,60 +10,128 @@
 
 public class Alerts extends AbstractModule {
 
+    /**
+     * Return a JSON list of current active alerts.
+     * @return <code>[{"id": 42, "nick_name": "frodo_b", ...}, ...]</code> JSON object of all the active alerts
+     * @throws RequestException
+     */
     public JSONArray getActive() throws RequestException {
         return requestBy("getActive")
             .withoutArgs().in(HttpMethod.GET).thenJsonArray();
     }
 
+    /**
+     * Return a JSON list of past 30 alerts.
+     * @return <code>[{"nick_name": "frodo_b", ...}, ...]</code> JSON object of all the history alerts
+     * @throws RequestException
+     */
     public JSONArray getHistory() throws RequestException {
         return requestBy("getHistory")
             .withoutArgs().in(HttpMethod.GET).thenJsonArray();
     }
 
+    /**
+     * Accept user_id as fan.
+     * @param user_id The user_id that has asked for friendship.
+     * @return <code>{"success_text": "ok"}</code>
+     * @throws RequestException
+     */
     public JSONObject addAsFan(Long user_id) throws RequestException {
         return addAsFan(user_id.toString());
     }
 
-	public JSONObject addAsFan(String user_id) throws RequestException {
+    /**
+     * Accept user_id as fan.
+     * @param user_id The user_id that has asked for friendship.
+     * @return <code>{"success_text": "ok"}</code>
+     * @throws RequestException
+     */
+    public JSONObject addAsFan(String user_id) throws RequestException {
 		return requestBy("addAsFan")
 	            .with(new Args().add("user_id", user_id))
 	            .in(HttpMethod.GET).thenJsonObject();
     }
 
+	/**
+	 * Accept all friendship requests as fans.
+	 * @return <code>{"success_text": "ok"}</code>
+	 * @throws RequestException
+	 */
 	public JSONArray addAllAsFan() throws RequestException {
         return requestBy("addAllAsFan")
             .withoutArgs().in(HttpMethod.GET).thenJsonArray();
     }
 
+	/**
+	 * Accept all friendship requests as friends.
+	 * @return <code>{"success_text": "ok"}</code>
+	 * @throws RequestException
+	 */
 	public JSONArray addAllAsFriends() throws RequestException {
         return requestBy("addAllAsFriends")
             .withoutArgs().in(HttpMethod.GET).thenJsonArray();
     }
 
+	/**
+	 * Accept user_id as friend.
+	 * @param user_id The user_id that has asked for friendship.
+	 * @return <code>{"success_text": "ok"}</code>
+	 * @throws RequestException
+	 */
 	public JSONObject addAsFriend(Long user_id) throws RequestException {
         return addAsFriend(user_id.toString());
     }
 
+	/**
+	 * Accept user_id as friend.
+	 * @param user_id The user_id that has asked for friendship.
+	 * @return <code>{"success_text": "ok"}</code>
+	 * @throws RequestException
+	 */
 	public JSONObject addAsFriend(String user_id) throws RequestException {
 		return requestBy("addAsFriend")
 	            .with(new Args().add("user_id", user_id))
 	            .in(HttpMethod.GET).thenJsonObject();
     }
 
+	/**
+	 * Deny friendship to user_id.
+	 * @param user_id The user_id that has asked for friendship.
+	 * @return <code>{"success_text": "ok"}</code>
+	 * @throws RequestException
+	 */
 	public JSONObject denyFriendship(Long user_id) throws RequestException {
         return denyFriendship(user_id.toString());
     }
 
+	/**
+	 * Deny friendship to user_id.
+	 * @param user_id The user_id that has asked for friendship.
+	 * @return <code>{"success_text": "ok"}</code>
+	 * @throws RequestException
+	 */
 	public JSONObject denyFriendship(String user_id) throws RequestException {
 		return requestBy("denyFriendship")
 	            .with(new Args().add("user_id", user_id))
 	            .in(HttpMethod.GET).thenJsonObject();
     }
 
+	/**
+	 * Remove notification to user with id user_id.
+	 * @param user_id The user_id that the current user has requested friendship for
+	 * @return <code>{"success_text": "ok"}</code>
+	 * @throws RequestException
+	 */
 	public JSONObject removeNotification(Long user_id) throws RequestException {
         return removeNotification(user_id.toString());
     }
 
+	/**
+	 * Remove notification to user with id user_id.
+	 * @param user_id The user_id that the current user has requested friendship for
+	 * @return <code>{"success_text": "ok"}</code>
+	 * @throws RequestException
+	 */
 	public JSONObject removeNotification(String user_id) throws RequestException {
 		return requestBy("removeNotification")
 	            .with(new Args().add("user_id", user_id))

diff --git a/src/main/java/com/google/jplurk_oauth/module/Blocks.java b/src/main/java/com/google/jplurk_oauth/module/Blocks.java
@@ -10,7 +10,7 @@
 public class Blocks extends AbstractModule {
 
 	/**
-	 * /APP/Blocks/get .
+	 * Get the block user list.
 	 * @return A JSON list of users that are blocked by the current user, e.g. <code>{"total": 12, "users": {"display_name": "amix3", "gender": 0, "nick_name": "amix", "has_profile_image": 1, "id": 1, "avatar": null}, ...]}</code>
      * @throws RequestException
 	 */
@@ -19,7 +19,7 @@ public JSONObject get() throws RequestException {
 	}
 
     /**
-     * /APP/Blocks/get .
+     * Get the block user list.
      * @param optional offset: What page should be shown, e.g. 0, 10, 20.
      * @return A JSON list of users that are blocked by the current user, e.g. <code>{"total": 12, "users": {"display_name": "amix3", "gender": 0, "nick_name": "amix", "has_profile_image": 1, "id": 1, "avatar": null}, ...]}</code>
      * @throws RequestException
@@ -31,7 +31,17 @@ public JSONObject get(Args optional) throws RequestException {
     }
 
     /**
-     * /APP/Blocks/block .
+     * Block the user with id user_id.
+     * @param user_id The id of the user that should be blocked.
+     * @return <code>{"success_text": "ok"}</code>
+     * @throws RequestException
+     */
+    public JSONObject block(Long user_id) throws RequestException {
+    	return block(user_id.toString());
+    }
+
+    /**
+     * Block the user with id user_id.
      * @param user_id The id of the user that should be blocked.
      * @return <code>{"success_text": "ok"}</code>
      * @throws RequestException
@@ -42,8 +52,19 @@ public JSONObject block(String user_id) throws RequestException {
             .in(HttpMethod.GET).thenJsonObject();
     }
 
+
+    /**
+     * Unblock the user with id user_id.
+     * @param user_id The id of the user that should be unblocked.
+     * @return <code>{"success_text": "ok"}</code>
+     * @throws RequestException
+     */
+    public JSONObject unblock(Long user_id) throws RequestException {
+    	return unblock(user_id.toString());
+    }
+
     /**
-     * /APP/Blocks/unblock .
+     * Unblock the user with id user_id.
      * @param user_id The id of the user that should be unblocked.
      * @return <code>{"success_text": "ok"}</code>
      * @throws RequestException

diff --git a/src/main/java/com/google/jplurk_oauth/module/Emoticons.java b/src/main/java/com/google/jplurk_oauth/module/Emoticons.java
@@ -9,8 +9,8 @@
 public class Emoticons extends AbstractModule {
 
     /**
-     * /APP/Emoticons/get .
-     * <p>Emoticons are a big part of Plurk since they make it easy to express feelings. Check out current Plurk emoticons.<p>
+     * Get the Emoticons list.
+     * <p>Emoticons are a big part of Plurk since they make it easy to express feelings.<p>
      * @return a JSON object.
      * @throws RequestException
      */

diff --git a/src/main/java/com/google/jplurk_oauth/module/Search.java b/src/main/java/com/google/jplurk_oauth/module/Search.java
@@ -15,9 +15,8 @@
 public class Search extends AbstractModule {
 
     /**
-     * /APP/PlurkSearch/search .
+     * Returns the latest 20 plurks on a search term.
      * <p>NOTE: It doesn't work now.</p>
-     * <p>Returns the latest 20 plurks on a search term.</p>
      * @param query The query after Plurks.
      * @return A JSON list of plurks that the user have permissions to see: [{"id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", ...}, ...]
      * @throws RequestException
@@ -27,9 +26,8 @@ public JSONArray plurkSearch(String query) throws RequestException {
     }
 
     /**
-     * /APP/PlurkSearch/search .
+     * Returns the latest 20 plurks on a search term.
      * <p>NOTE: It doesn't work now.</p>
-     * <p>Returns the latest 20 plurks on a search term.</p>
      * @param query The query after Plurks.
      * @param optional offset: A plurk_id of the oldest Plurk in the last search result.
      * @return A JSON list of plurks that the user have permissions to see: [{"id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", ...}, ...]
@@ -42,9 +40,8 @@ public JSONArray plurkSearch(String query, Args optional) throws RequestExceptio
     }
 
     /**
-     * /APP/UserSearch/search .
+     * Returns 10 users that match query, users are sorted by karma.
      * <p>NOTE: The return description said the return is JSON list, but actually it is JSON Object.</p>  
-     * <p>Returns 10 users that match query, users are sorted by karma.</p>
      * @param query The query after users.
      * @return A JSON Object
      * @throws RequestException
@@ -54,9 +51,8 @@ public JSONObject userSearch(String query) throws RequestException {
     }
 
     /**
-     * /APP/UserSearch/search .
+     * Returns 10 users that match query, users are sorted by karma.
      * <p>NOTE: The return description said the return is JSON list, but actually it is JSON Object.</p> 
-     * <p>Returns 10 users that match query, users are sorted by karma.</p>
      * @param query The query after users.
      * @param optional offset: Page offset, like 10, 20, 30 etc.
      * @return A JSON Object