Updated javadoc

4 files changed, 65 insertions, 21 deletions

diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/ISubscriberChangeEvent.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/ISubscriberChangeEvent.java
index 0f644794a..bb0c8fef4 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/ISubscriberChangeEvent.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/ISubscriberChangeEvent.java
@@ -10,6 +10,13 @@
  *******************************************************************************/
 package org.eclipse.team.core.subscribers;
 import org.eclipse.core.resources.IResource;
+
+/**
+ * A change event that describes a change in a resource
+ * that is or was supervised by a subscriber.
+ * @see ISubscriberChangeListener
+ * @since 3.0
+ */
 public interface ISubscriberChangeEvent {
 	/*====================================================================
 	 * Constants defining the kinds of team changes to resources:
@@ -21,19 +28,45 @@ public interface ISubscriberChangeEvent {
 	public static final int NO_CHANGE = 0;
 	/**
 	 * Delta kind constant (bit mask) indicating that the synchronization state of a resource has changed.
+	 * @see #getFlags
 	 */
 	public static final int SYNC_CHANGED = 0x1;
 	/**
 	 * Delta kind constant (bit mask) indicating that a team provider has been configured on the resource.
-	 * @see IResourceDelta#getKind
+	 * @see  #getFlags
 	 */
 	public static final int ROOT_ADDED = 0x2;
 	/**
 	 * Delta kind constant (bit mask) indicating that a team provider has been de-configured on the resource.
-	 * @see IResourceDelta#getKind
+	 * @see #getFlags
 	 */
 	public static final int ROOT_REMOVED = 0x4;
+	
+	/**
+	 * Return the flags that describe the type of change.
+	 * The returned value should be ANDed with the change type
+	 * flags to determine whether the change event is of 
+	 * a particular type. For exampe,
+	 * <pre>
+	 *   if (event.getFlags() & ISubscriberChangeEvent.SYNC_CHANGED) {
+	 *      // the sync info for the resource has changed
+	 *   }
+	 * </pre>
+	 * @return the flags that describe the type of change
+	 */
 	public abstract int getFlags();
+	
+	/**
+	 * Return the resource whose state with
+	 * respect to the subscriber has changed.
+	 * @return the resource whose state with
+	 * respect to the subscriber has changed
+	 */
 	public abstract IResource getResource();
+	
+	/**
+	 * Return the subscriber to which this change event applies.
+	 * @return the subscriber to which this change event applies
+	 */
 	public abstract Subscriber getSubscriber();
 }
\ No newline at end of file
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/ISubscriberChangeListener.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/ISubscriberChangeListener.java
index 4360d33f3..699202ce2 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/ISubscriberChangeListener.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/ISubscriberChangeListener.java
@@ -14,30 +14,23 @@ package org.eclipse.team.core.subscribers;
 import java.util.EventListener;
 
 /**
- * A resource state change listener is notified of changes to resources
- * regarding their team state. 
+ * A subscriber change listener is notified of changes to resources
+ * regarding their subscriber synchronization state. 
  * <p>
  * Clients may implement this interface.
  * </p>
- * @see ITeamManager#addResourceStateChangeListener(IResourceStateChangeListener)
+ * @see Subscriber#addListener(ISubscriberChangeListener)
+ * @since 3.0
  */
 public interface ISubscriberChangeListener extends EventListener{
 	
 	/**
-	 * Notifies this listener that some resources' team properties have
+	 * Notifies this listener that some resources' subscriber properties have
 	 * changed. The changes have already happened. For example, a resource's 
-	 * base revision may have changed. The resource tree is open for modification 
-	 * when this method is invoked, so markers can be created, etc.
-	 * <p>
-	 * Note: This method is called by Team core; it is not intended to be
-	 * called directly by clients.
-	 * </p>
+	 * base revision may have changed. The resource tree may or may not be open for modification 
+	 * when this method is invoked.
 	 *
-	 * @param deltas detailing the kinds of team changes
-	 * 
-	 * [Note: The changed state event is purposely vague. For now it is only
-	 * a hint to listeners that they should query the provider to determine the
-	 * resources new sync info.]
+	 * @param deltas detailing the kinds of changes
 	 */
 	public void subscriberResourceChanged(ISubscriberChangeEvent[] deltas);
 }
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/Subscriber.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/Subscriber.java
index 5ff4bce79..134eca11d 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/Subscriber.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/Subscriber.java
@@ -63,6 +63,7 @@ import org.eclipse.team.internal.core.TeamPlugin;
  * or incoming additions). When queried for the members of a local resource, the subscriber should include any children
  * for which a remote exists even if the local does not.
  * 
+ * @since 3.0
  */
 abstract public class Subscriber {
 
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/SubscriberChangeEvent.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/SubscriberChangeEvent.java
index 13c0de9c4..67754db14 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/SubscriberChangeEvent.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/subscribers/SubscriberChangeEvent.java
@@ -17,7 +17,9 @@ import org.eclipse.core.resources.IResource;
  * be used by clients.
  *
  * @see IResource
- * @see ITeamProvider
+ * @see Subscriber
+ * 
+ * @since 3.0
  */
 public class SubscriberChangeEvent implements ISubscriberChangeEvent {
 
@@ -25,29 +27,44 @@ public class SubscriberChangeEvent implements ISubscriberChangeEvent {
 	private int flags;
 	private IResource resource; 
 	
+	/**
+	 * Create a cahnge event with the given flags for the given subscriber and resource.
+	 * @param subscriber the subscriber to which the state change applies
+	 * @param flags the flags that describe the change
+	 * @param resource the resource whose state has change
+	 */
 	public SubscriberChangeEvent(Subscriber subscriber, int flags, IResource resource) {
 		this.subscriber = subscriber;
 		this.flags = flags;
 		this.resource = resource;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.team.core.subscribers.ISubscriberChangeEvent#getFlags()
+	 */
 	public int getFlags() {
 		return flags;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.team.core.subscribers.ISubscriberChangeEvent#getResource()
+	 */
 	public IResource getResource() {
 		return resource;
 	}
 
+	/* (non-Javadoc)
+	 * @see org.eclipse.team.core.subscribers.ISubscriberChangeEvent#getSubscriber()
+	 */
 	public Subscriber getSubscriber() {
 		return subscriber;
 	}
 	
 	/**
-	 * Returns an array of deltas for the resources with SubscriberChangeEvent.SYNC_CHANGED
-	 * as the change type.
+	 * Returns an array of deltas for the resources with <code>ISubscriberChangeEvent.SYNC_CHANGED</code>
+	 * as the flag.
 	 * @param resources the resources whose sync info has changed
-	 * @return an array of events
+	 * @return an array of change events
 	 */
 	public static SubscriberChangeEvent[] asSyncChangedDeltas(Subscriber subscriber, IResource[] resources) {
 		SubscriberChangeEvent[] deltas = new SubscriberChangeEvent[resources.length];