Updated docs for IRosterSubscriptionSender

1 files changed, 28 insertions, 13 deletions

diff --git a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/roster/IRosterSubscriptionSender.java b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/roster/IRosterSubscriptionSender.java
index 574bc5faa..ea0f2c591 100644
--- a/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/roster/IRosterSubscriptionSender.java
+++ b/framework/bundles/org.eclipse.ecf.presence/src/org/eclipse/ecf/presence/roster/IRosterSubscriptionSender.java
@@ -16,32 +16,47 @@ import org.eclipse.ecf.core.util.ECFException;
 public interface IRosterSubscriptionSender {
 
 	/**
-	 * Send a roster add request (subscribe) to a remote
+	 * Send a request to add the userAccount (subscribe) to our roster. This
+	 * initiates an asynchronous request to add the given userAccount to the
+	 * local roster with the given nickname in the given groups. If successful,
+	 * the roster will be asynchronously updated via calls to
+	 * {@link IRosterListener#handleRosterEntryAdd(IRosterEntry)} and
+	 * {@link IRosterListener#handleRosterUpdate(IRoster, IRosterItem)}
 	 * 
-	 * @param user
-	 *            the account name of the target user. Should not be
-	 *            <code>null</code>.
+	 * @param userAccount
+	 *            the account of the roster add request. Must not be
+	 *            <code>null</code>. e.g. "fliwatuet@foo.bar".
+	 * @param nickname
+	 *            or local alias for userAccount. May be <code>null</code>.
+	 *            e.g. "Steve"
 	 * @param groups
-	 *            an array of group names that this use will belong to on the
-	 *            roster entry. Should not be <code>null</code>.
+	 *            an array of group names that this use will belong to. May be
+	 *            <code>null</code> if userAccount not intended to be in any
+	 *            groups. e.g. [ "ECF", "Eclipse" ].
 	 * 
 	 * @exception ECFException
 	 *                thrown if request cannot be sent (e.g. because of previous
-	 *                disconnect
+	 *                disconnect) or server refuses to change as desired (e.g.
+	 *                insufficient permissions).
 	 */
-	public void sendRosterAdd(String user, String name, String[] groups)
-			throws ECFException;
+	public void sendRosterAdd(String userAccount, String nickname,
+			String[] groups) throws ECFException;
 
 	/**
-	 * Send roster remove request (unsubscribe) to a remote
+	 * Send a request to remove a given userID (unsubscribe) from our roster.
+	 * This initiates an asynchronous request to remove the given userID from
+	 * our local roster. If successfully removed, the roster will be
+	 * asynchronously updated via calls to
+	 * {@link IRosterListener#handleRosterEntryRemove(IRosterEntry)} and
+	 * {@link IRosterListener#handleRosterUpdate(IRoster, IRosterItem)}.
 	 * 
 	 * @param userID
-	 *            the user id the request it is intended for. Should not be
-	 *            <code>null</code>
+	 *            the user ID to remove. Must not be <code>null</code>.
 	 * 
 	 * @exception ECFException
 	 *                thrown if request cannot be sent (e.g. because of previous
-	 *                disconnect
+	 *                disconnect) or server refuses change as desired (e.g.
+	 *                insufficient permissions).
 	 */
 	public void sendRosterRemove(ID userID) throws ECFException;