/soc/2012/michael/android: f5645b56981a: Commented buddy classes

Michael Zangl michael at soc.pidgin.im
Mon Aug 20 10:15:53 EDT 2012


Changeset: f5645b56981a6868c55c784fe0b2a9fa86e655f1
Author:	 Michael Zangl <michael at soc.pidgin.im>
Date:	 2012-08-20 15:17 +0200
Branch:	 soc.2012.android
URL: http://hg.pidgin.im/soc/2012/michael/android/rev/f5645b56981a

Description:

Commented buddy classes

diffstat:

 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddy.java         |  98 ++++++++-
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddyListener.java |  30 +++
 2 files changed, 113 insertions(+), 15 deletions(-)

diffs (239 lines):

diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddy.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddy.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddy.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddy.java
@@ -10,21 +10,55 @@ import im.pidgin.libpurple.icon.PurpleSt
 
 import java.util.LinkedList;
 
+/**
+ * This is a buddy from the buddy list. Each buddy represents a other account
+ * that our account is connected to and may start an IM conversation with.
+ *
+ * @author michael
+ */
 public class PurpleBuddy extends PurpleBlistNode {
 
+	/**
+	 * The listeners that listen to changes of this buddy.
+	 */
+	private final LinkedList<PurpleBuddyListener> buddyListeners =
+	        new LinkedList<PurpleBuddyListener>();
+	/**
+	 * The mutex that synchronizes listeners.
+	 */
+	private final Object buddyMutex = new Object();
+
+	/**
+	 * Creates a new buddy object.
+	 *
+	 * @param nativePointer
+	 *            The native pointer to use
+	 * @param manager
+	 *            The manager
+	 */
 	public PurpleBuddy(long nativePointer, CoreManager manager) {
 		super(nativePointer, manager);
 	}
-	
-	private final LinkedList<PurpleBuddyListener> buddyListeners = new LinkedList<PurpleBuddyListener>();
-	private final Object buddyMutex = new Object();
 
+	/**
+	 * Adds a buddy listener.
+	 *
+	 * @param l
+	 *            The listener to add.
+	 */
 	public void addBuddyListener(PurpleBuddyListener l) {
 		synchronized (buddyMutex) {
 			buddyListeners.add(l);
 		}
 	}
 
+	/**
+	 * Removes a buddy listener, if it is in the list of registered buddy
+	 * listeners.
+	 *
+	 * @param l
+	 *            The buddy listener to remove.
+	 */
 	public void removeBuddyListener(PurpleBuddyListener l) {
 		synchronized (buddyMutex) {
 			buddyListeners.remove(l);
@@ -64,7 +98,6 @@ public class PurpleBuddy extends PurpleB
 		}
 	}
 
-
 	/**
 	 * TODO: Make this more private.
 	 */
@@ -76,24 +109,46 @@ public class PurpleBuddy extends PurpleB
 		}
 	}
 
+	/**
+	 * Returns a buddy's name.
+	 *
+	 * @return The name.
+	 */
 	public String getName() {
 		return getName_native();
 	}
 
 	private native String getName_native();
 
+	/**
+	 * Gets the alias for this buddy.
+	 *
+	 * @return Returns the alias of a buddy. TODO: This method returns the alias
+	 *         previously set with setAlias. TODO: Provide a getDisplayName()
+	 */
 	public String getAlias() {
 		return getAlias_native();
 	}
 
 	private native String getAlias_native();
 
+	/**
+	 * Sets a local alias for the buddy.
+	 *
+	 * @param alias
+	 *            The local alias, or TODO: null to delete the alias.
+	 */
 	public void setAlias(String alias) {
 		setAlias_native(alias);
 	}
 
 	private native void setAlias_native(String alias);
-	
+
+	/**
+	 * Gets the alias the server suggests for this buddy.
+	 *
+	 * @return The server alias.
+	 */
 	public String getServerAlias() {
 		return getServerAlias_native();
 	}
@@ -102,7 +157,7 @@ public class PurpleBuddy extends PurpleB
 
 	/**
 	 * Gets the name that should be used to display this buddy.
-	 * 
+	 *
 	 * @return The display name, which is the first of alias, parent.alias,
 	 *         server_alias, name that is not null.
 	 */
@@ -112,6 +167,11 @@ public class PurpleBuddy extends PurpleB
 
 	private native String getDisplayName_native();
 
+	/**
+	 * Gets the account for the buddy.
+	 *
+	 * @return The account this buddy is on.
+	 */
 	public PurpleAccount getAccount() {
 		return getManager().getAccountList().getPeer(getAccount_native());
 	}
@@ -120,7 +180,7 @@ public class PurpleBuddy extends PurpleB
 
 	/**
 	 * Checks if the buddy is online
-	 * 
+	 *
 	 * @return true if the account of the buddy is online and the buddy has an
 	 *         online presence.
 	 */
@@ -130,22 +190,29 @@ public class PurpleBuddy extends PurpleB
 
 	private native boolean isOnline_native();
 
+	/**
+	 * Gets the contact for this buddy.
+	 *
+	 * @return A contact object this account is on.
+	 */
 	public PurpleContact getContact() {
 		PurpleBlistManager blist = getManager().getBlist();
-		PurpleBlistNode contact = blist.getPeer(getContact_native());
-		if (contact instanceof PurpleContact) {
-			return (PurpleContact) contact;
-		} else {
-			return null;
-		}
+		PurpleContact contact = blist.getContactPeer(getContact_native());
+		return contact;
 	}
 
 	private native long getContact_native();
-	
+
+	/**
+	 * Starts a new conversation with this buddy.
+	 *
+	 * @return A {@link PurpleConversation} you can register to and send
+	 *         messages with.
+	 */
 	public PurpleConversation newConversation() {
 		return getManager().getConversationManager().newConversation(this);
 	}
-	
+
 	@Override
 	public PurpleStoredImage getSuggestedIcon() {
 		PurpleStoredImage customIcon = getCustomIcon();
@@ -157,6 +224,7 @@ public class PurpleBuddy extends PurpleB
 
 	/**
 	 * Gets the icon for this buddy that is given by the protocol.
+	 *
 	 * @return the icon.
 	 */
 	public PurpleStoredImage getIcon() {
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddyListener.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddyListener.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddyListener.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/buddy/PurpleBuddyListener.java
@@ -1,11 +1,41 @@
 package im.pidgin.libpurple.buddy;
 
+/**
+ * This is a listener interface for classes that want to listen to buddy
+ * changes.
+ *
+ * @author michael
+ */
 public interface PurpleBuddyListener {
+	/**
+	 * Gets called when the idle status of the buddy changed.
+	 *
+	 * @param purpleBuddy
+	 *            The buddy that changed.
+	 */
 	void buddyIdleChanged(PurpleBuddy purpleBuddy);
 
+	/**
+	 * Gets called when the buddy icon was changed.
+	 *
+	 * @param purpleBuddy
+	 *            The buddy that changed.
+	 */
 	void buddyIconChanged(PurpleBuddy purpleBuddy);
 
+	/**
+	 * Gets called when the status of the buddy changed.
+	 *
+	 * @param purpleBuddy
+	 *            The buddy that changed.
+	 */
 	void buddyStatusChanged(PurpleBuddy purpleBuddy);
 
+	/**
+	 * Gets called when the buddy signed on or off.
+	 *
+	 * @param purpleBuddy
+	 *            The buddy that changed.
+	 */
 	void buddySignedOnOff(PurpleBuddy purpleBuddy);
 }



More information about the Commits mailing list