/soc/2012/michael/android: 1959cd30f5be: Added more comments to ...

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


Changeset: 1959cd30f5bea347128d34e68adc9266ea76031f
Author:	 Michael Zangl <michael at soc.pidgin.im>
Date:	 2012-08-20 14:40 +0200
Branch:	 soc.2012.android
URL: http://hg.pidgin.im/soc/2012/michael/android/rev/1959cd30f5be

Description:

Added more comments to account classes

diffstat:

 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/AccountListenerList.java     |    6 +-
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/PurpleAccount.java           |  117 ++++++---
 android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/PurpleAccountListenable.java |    6 +
 3 files changed, 88 insertions(+), 41 deletions(-)

diffs (270 lines):

diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/AccountListenerList.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/AccountListenerList.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/AccountListenerList.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/AccountListenerList.java
@@ -3,7 +3,7 @@ package im.pidgin.libpurple.account;
 import java.util.LinkedList;
 
 /**
- * This class holds a list of account listeners that can be notified.
+ * This class holds a list of account listeners that can be notified all at once.
  * @author michaelz
  *
  */
@@ -20,6 +20,10 @@ class AccountListenerList implements Pur
 		listeners.remove(listener);
 	}
 
+	/**
+	 * Notifies all added account listeners of an account properties changed event.
+	 * @param purpleAccount The account that has changed.
+	 */
 	public synchronized void notifyPropertiesChanged(PurpleAccount purpleAccount) {
 		for (PurpleAccountListener l : listeners) {
 			l.accountPropertiesChanged(purpleAccount);
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/PurpleAccount.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/PurpleAccount.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/PurpleAccount.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/PurpleAccount.java
@@ -11,15 +11,23 @@ import im.pidgin.libpurple.plugin.Purple
  * This is an account of libpurple.
  * 
  * @author michaelz
- * 
  */
 public final class PurpleAccount extends PeeredPurpleManaged {
 
 	/**
 	 * Listeners that just listen to us.
 	 */
-	private final AccountListenerList individualAccountListeners = new AccountListenerList();
+	private final AccountListenerList individualAccountListeners =
+	        new AccountListenerList();
 
+	/**
+	 * Creates a new purple account.
+	 * 
+	 * @param nativePointer
+	 *            The pointer to the native account object
+	 * @param manager
+	 *            The core manager to use.
+	 */
 	public PurpleAccount(long nativePointer, CoreManager manager) {
 		super(nativePointer, manager);
 	}
@@ -33,7 +41,7 @@ public final class PurpleAccount extends
 	/**
 	 * Gets the username of the account
 	 * 
-	 * @return
+	 * @return The username as String.
 	 */
 	public String getUsername() {
 		return getUsername_native();
@@ -109,12 +117,12 @@ public final class PurpleAccount extends
 	 */
 	public void setPassword(final String password) {
 		getManager().getThread().scheduleAndWaitForUninterruptable(
-				new AbstractWaitableRunnable() {
-					@Override
-					protected void execute() {
-						setPassword_native(password);
-					}
-				});
+		        new AbstractWaitableRunnable() {
+			        @Override
+			        protected void execute() {
+				        setPassword_native(password);
+			        }
+		        });
 		notifyPropertiesChanged();
 	}
 
@@ -139,12 +147,12 @@ public final class PurpleAccount extends
 	 */
 	public void setRememberPassword(final boolean remember) {
 		getManager().getThread().scheduleAndWaitForUninterruptable(
-				new AbstractWaitableRunnable() {
-					@Override
-					protected void execute() {
-						setRememberPassword_native(remember);
-					}
-				});
+		        new AbstractWaitableRunnable() {
+			        @Override
+			        protected void execute() {
+				        setRememberPassword_native(remember);
+			        }
+		        });
 		notifyPropertiesChanged();
 	}
 
@@ -164,9 +172,14 @@ public final class PurpleAccount extends
 	//
 	// private native void register_native();
 
+	/**
+	 * Gets the protocol this account uses.
+	 * 
+	 * @return The protocol plugin.
+	 */
 	public PurpleProtocolPlugin getProtocol() {
 		return getManager().getPluginManager().getProtocolPlugin(
-				getProtocol_native());
+		        getProtocol_native());
 	}
 
 	private native String getProtocol_native();
@@ -190,40 +203,42 @@ public final class PurpleAccount extends
 	 */
 	public void setEnabled(final boolean enabled) {
 		getManager().getThread().scheduleAndWaitForUninterruptable(
-				new AbstractWaitableRunnable() {
-					@Override
-					protected void execute() {
-						setEnabled_native(enabled);
-					}
-				});
+		        new AbstractWaitableRunnable() {
+			        @Override
+			        protected void execute() {
+				        setEnabled_native(enabled);
+			        }
+		        });
 		notifyStatusChanged();
 	}
 
 	private native void setEnabled_native(boolean enabled);
 
 	/**
-	 * Creates a new buddy and adds it to this account.
-	 * 
-	 * XXX This function only creates the PurpleBuddy. Use
-	 * purple_blist_add_buddy to add the buddy to the list and
-	 * purple_account_add_buddy to sync up with the server.
+	 * Creates a new buddy and adds it to this account. XXX This function only
+	 * creates the PurpleBuddy. Use purple_blist_add_buddy to add the buddy to
+	 * the list and purple_account_add_buddy to sync up with the server.
 	 * 
 	 * @param name
 	 *            The name of the new buddy
 	 * @param alias
 	 *            The alias of the new buddy (or <code>null</code> if unaliased)
 	 * @return The new buddy
-	 * 
 	 * @see PurpleBlistGroup#addBuddy(PurpleBuddy)
 	 * @see PurpleBlistContact#addBuddy(PurpleBuddy)
 	 */
 	public PurpleBuddy newBuddy(String name, String alias) {
 		return getManager().getBlist().getBuddyPeer(
-				newBuddy_native(name, alias));
+		        newBuddy_native(name, alias));
 	}
 
 	private native long newBuddy_native(String name, String alias);
 
+	/**
+	 * Clears all account settings.
+	 * 
+	 * @see #removeSetting(String)
+	 */
 	public void clearSettings() {
 		clearSettings_native();
 	}
@@ -231,8 +246,10 @@ public final class PurpleAccount extends
 	private native void clearSettings_native();
 
 	/**
-	 * Removes an account-specific setting by name. 
+	 * Removes an account-specific setting by name.
+	 * 
 	 * @param setting
+	 *            The name of the setting to remove.
 	 */
 	public void removeSetting(String setting) {
 		removeSetting_native(setting);
@@ -240,41 +257,61 @@ public final class PurpleAccount extends
 
 	private native void removeSetting_native(String setting);
 
+	/**
+	 * Sets a protocol-specific integer setting for an account.
+	 * 
+	 * @param setting
+	 *            The name of the setting.
+	 * @param value
+	 *            The setting's value.
+	 */
 	public void setInt(String setting, int value) {
 		setInt_native(setting, value);
 	}
 
 	private native void setInt_native(String setting, int value);
-	
+
+	/**
+	 * Sets a protocol-specific string setting for an account.
+	 * 
+	 * @param setting
+	 *            The name of the setting.
+	 * @param value
+	 *            The setting's value.
+	 */
 	public void setString(String setting, String value) {
 		setString_native(setting, value);
 	}
 
 	private native void setString_native(String setting, String value);
-	
 
+	/**
+	 * Sets a protocol-specific boolean setting for an account.
+	 * 
+	 * @param setting
+	 *            The name of the setting.
+	 * @param value
+	 *            The setting's value.
+	 */
 	public void setBool(String setting, boolean value) {
 		setBool_native(setting, value);
 	}
 
 	private native void setBool_native(String setting, boolean value);
-	
-	
-	
-	
+
 	/**
 	 * Creates a new purple account by calling purple_account_new.
 	 * <p>
 	 * This creates a new, unbound native object so be sure to free it somehow
 	 * or add it to the global list of accounts.
 	 * 
-	 * @param manager
-	 * @param name
-	 * @param protocol
+	 * @param manager The manager to use.
+	 * @param name The username on the server
+	 * @param protocol The protocol.
 	 * @return A new purple account.
 	 */
 	protected static PurpleAccount newAccount(CoreManager manager, String name,
-			PurpleProtocolPlugin protocol) {
+	        PurpleProtocolPlugin protocol) {
 		long account_native = newAccount_native(name, protocol.getId());
 		if (account_native == 0) {
 			throw new NullPointerException("Native account was null.");
diff --git a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/PurpleAccountListenable.java b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/PurpleAccountListenable.java
--- a/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/PurpleAccountListenable.java
+++ b/android/workspace/im.pidgin.libpurple/src/im/pidgin/libpurple/account/PurpleAccountListenable.java
@@ -1,5 +1,11 @@
 package im.pidgin.libpurple.account;
 
+/**
+ * This interface defines a class that is able to listen to account list
+ * changes.
+ * 
+ * @author michael
+ */
 interface PurpleAccountListenable {
 
 	/**



More information about the Commits mailing list