/soc/2012/michael/android: 52d1f95ae851: Fixed typo in NodeIter(...

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


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

Description:

Fixed typo in NodeIter(r)ator class, added documentation to buddy classes

diffstat:

 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterator.java        |  42 +++++
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterrator.java       |  33 ----
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlist.java         |  24 +++
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistGroup.java    |  19 ++
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistListener.java |  30 +++
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistManager.java  |  78 +++++++--
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistNode.java     |  72 +++++++-
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleContact.java       |  15 +
 8 files changed, 252 insertions(+), 61 deletions(-)

diffs (truncated from 542 to 300 lines):

diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterator.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterator.java
new file mode 100644
--- /dev/null
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterator.java
@@ -0,0 +1,42 @@
+package im.pidgin.libpurple.blist;
+
+import java.util.Iterator;
+
+/**
+ * This is a node iterator that iterates over the children of a node.
+ * @author michael
+ *
+ */
+public class NodeIterator implements Iterator<PurpleBlistNode> {
+
+	private PurpleBlistNode next;
+
+	/**
+	 * Creates a new {@link NodeIterator} that iterates over all children of the given node.
+	 * @param blistNode The node.
+	 */
+	public NodeIterator(PurpleBlistNode blistNode) {
+		next = blistNode.getFirstChild();
+	}
+
+	@Override
+	public boolean hasNext() {
+		return next != null;
+	}
+
+	@Override
+	public PurpleBlistNode next() {
+		if (next == null) {
+			throw new IllegalStateException();
+		}
+		PurpleBlistNode result = next;
+		next = next.getNextSibling();
+		return result;
+	}
+
+	@Override
+	public void remove() {
+		throw new UnsupportedOperationException();
+	}
+
+}
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterrator.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterrator.java
deleted file mode 100644
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/NodeIterrator.java
+++ /dev/null
@@ -1,33 +0,0 @@
-package im.pidgin.libpurple.blist;
-
-import java.util.Iterator;
-
-public class NodeIterrator implements Iterator<PurpleBlistNode> {
-
-	private PurpleBlistNode next;
-
-	public NodeIterrator(PurpleBlistNode blistNode) {
-		next = blistNode.getFirstChild();
-	}
-
-	@Override
-	public boolean hasNext() {
-		return next != null;
-	}
-
-	@Override
-	public PurpleBlistNode next() {
-		if (next == null) {
-			throw new IllegalStateException();
-		}
-		PurpleBlistNode result = next;
-		next = next.getNextSibling();
-		return result;
-	}
-
-	@Override
-	public void remove() {
-		throw new UnsupportedOperationException();
-	}
-
-}
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlist.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlist.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlist.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlist.java
@@ -1,11 +1,35 @@
 package im.pidgin.libpurple.blist;
 
+/**
+ * This is the main entry point to the buddy list libpurple provides.
+ * 
+ * @author michael
+ */
 public interface PurpleBlist {
 
+	/**
+	 * Gets the root node of the buddy list. The root node is normally a group
+	 * and it may have some siblings.
+	 * 
+	 * @return The root node.
+	 */
 	PurpleBlistNode getRoot();
 
+	/**
+	 * Adds a listener that listens to buddy list events.
+	 * 
+	 * @param l
+	 *            The listener to add.
+	 */
 	void addBlistListener(PurpleBlistListener l);
 
+	/**
+	 * Removes a previously added listener from the buddy list, or does nothing
+	 * if the listener was not added.
+	 * 
+	 * @param l
+	 *            The listener to remove.
+	 */
 	void removeBlistListener(PurpleBlistListener l);
 
 }
\ No newline at end of file
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistGroup.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistGroup.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistGroup.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistGroup.java
@@ -3,12 +3,31 @@ package im.pidgin.libpurple.blist;
 import im.pidgin.libpurple.buddy.PurpleBuddy;
 import im.pidgin.libpurple.core.CoreManager;
 
+/**
+ * This is a group of contacts in the buddy list.
+ * 
+ * @author michael
+ */
 public class PurpleBlistGroup extends PurpleBlistNode {
 
+	/**
+	 * Creates a new group.
+	 * 
+	 * @param nativePointer
+	 *            The native pointer
+	 * @param manager
+	 *            The manager to use.
+	 * @see PurpleBlistManager#getGroupPeer(long)
+	 */
 	protected PurpleBlistGroup(long nativePointer, CoreManager manager) {
 		super(nativePointer, manager);
 	}
 
+	/**
+	 * Gets the name of the buddy list group.
+	 * 
+	 * @return The name.
+	 */
 	public String getName() {
 		return getName_native();
 	}
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistListener.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistListener.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistListener.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistListener.java
@@ -2,12 +2,42 @@ package im.pidgin.libpurple.blist;
 
 import im.pidgin.libpurple.buddy.PurpleBuddy;
 
+/**
+ * Listeners that listen to the buddy list need to implement this interface.
+ * @author michael
+ *
+ */
 public interface PurpleBlistListener {
 
+	/**
+	 * Called when any node was added, also when a buddy was added.
+	 * @param node The node that was added
+	 */
 	void nodeAdded(PurpleBlistNode node);
+	/**
+	 * Called when any node was removed, also when a buddy was added.
+	 * @param node The node that was removed.
+	 */
 	void nodeRemoved(PurpleBlistNode node);
+	
+	/**
+	 * Called when a buddy was added to the buddy list.
+	 * @param node The buddy that was added.
+	 * @see PurpleBlistListener#nodeAdded(PurpleBlistNode)
+	 */
 	void buddyAdded(PurpleBuddy node);
+	
+	/**
+	 * Called when a buddy was removed from the buddy list.
+	 * @param node The buddy that was removed.
+	 * @see PurpleBlistListener#nodeRemoved(PurpleBlistNode)
+	 */
 	void buddyRemoved(PurpleBuddy node);
+	
+	/**
+	 * Called when the alias for a node was changed.
+	 * @param node The node who's alias was changed.
+	 */
 	void nodeAliasChanged(PurpleBlistNode node);
 
 }
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistManager.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistManager.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistManager.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/blist/PurpleBlistManager.java
@@ -13,19 +13,26 @@ import java.util.LinkedList;
  * need to have a node cache here.
  * 
  * @author michaelz
- * 
  */
 public class PurpleBlistManager extends AbstractPurpleManaged implements
-		PeerGenerator<PurpleBlistNode>, PurpleBlist {
+        PeerGenerator<PurpleBlistNode>, PurpleBlist {
 
 	public PurpleBlistManager(CoreManager coreManager) {
 		super(coreManager);
 	}
 
-	private final LinkedList<PurpleBlistListener> blistListeners = new LinkedList<PurpleBlistListener>();
+	/**
+	 * This is a list of listeners that listen to structural buddy list changes.
+	 */
+	private final LinkedList<PurpleBlistListener> blistListeners =
+	        new LinkedList<PurpleBlistListener>();
+	/**
+	 * This is the mutex used for synchronizing buddy list listener access.
+	 */
 	private final Object blistMutex = new Object();
 
-	/* (non-Javadoc)
+	/*
+	 * (non-Javadoc)
 	 * @see im.pidgin.libpurple.blist.PurpleBlist#getRoot()
 	 */
 	@Override
@@ -35,6 +42,10 @@ public class PurpleBlistManager extends 
 
 	private native long getRoot_native();
 
+	/**
+	 * Registers the native part of this manager. To be called on libpurple
+	 * start.
+	 */
 	public void register() {
 		register_native();
 	}
@@ -59,6 +70,15 @@ public class PurpleBlistManager extends 
 		return object.getNativePointer();
 	}
 
+	/**
+	 * Gets the java object for a native buddy pointer.
+	 * 
+	 * @param pointer
+	 *            The pointer
+	 * @return The buddy object
+	 * @throws IllegalArgumentException
+	 *             If the pointer is not a buddy node.
+	 */
 	public PurpleBuddy getBuddyPeer(long pointer) {
 		PurpleBlistNode peer = getPeer(pointer);
 		if (peer instanceof PurpleBuddy) {
@@ -68,6 +88,15 @@ public class PurpleBlistManager extends 
 		}
 	}
 
+	/**
+	 * Gets the java object for a native group pointer.
+	 * 
+	 * @param pointer
+	 *            The pointer
+	 * @return The buddy object
+	 * @throws IllegalArgumentException
+	 *             If the pointer is not a group node.
+	 */
 	public PurpleBlistGroup getGroupPeer(long pointer) {
 		PurpleBlistNode peer = getPeer(pointer);
 		if (peer instanceof PurpleBlistGroup) {
@@ -77,19 +106,30 @@ public class PurpleBlistManager extends 
 		}
 	}
 
+	/**
+	 * Gets the java object for a native contact pointer.
+	 * 
+	 * @param pointer
+	 *            The pointer
+	 * @return The contact object
+	 * @throws IllegalArgumentException
+	 *             If the pointer is not a contact node.
+	 */
 	public PurpleContact getContactPeer(long pointer) {
 		PurpleBlistNode peer = getPeer(pointer);
 		if (peer instanceof PurpleContact) {
 			return (PurpleContact) peer;



More information about the Commits mailing list