Javadoc updates

15 files changed, 111 insertions, 65 deletions

diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/AbstractResourceVariantTree.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/AbstractResourceVariantTree.java
index c4cd9c92e..dbda326e5 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/AbstractResourceVariantTree.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/AbstractResourceVariantTree.java
@@ -28,7 +28,6 @@ import org.eclipse.team.core.TeamException;
 import org.eclipse.team.internal.core.Assert;
 import org.eclipse.team.internal.core.Policy;
 
-
 /**
  * An implemenation of <code>IResourceVariantTree</code> that provides the logic for
  * refreshing the tree and collecting the results so they can be cached locally.
@@ -127,8 +126,8 @@ public abstract class AbstractResourceVariantTree implements IResourceVariantTre
 
 	/**
 	 * Fetch the members of the given resource variant handle. This method may
-	 * return members that were fetched when <code>getRemoteTree</code> was called or
-	 * may fetch the children directly. 
+	 * return members that were fetched when <code>fetchVariant</code> was called or
+	 * may fetch the children directly (i.e. this method may contact the server). 
 	 * @param variant the resource variant
 	 * @param progress a progress monitor
 	 * @return the members of the resource variant.
@@ -136,14 +135,13 @@ public abstract class AbstractResourceVariantTree implements IResourceVariantTre
 	protected abstract IResourceVariant[] fetchMembers(IResourceVariant variant, IProgressMonitor progress) throws TeamException;
 
 	/**
-	 * Fetch the resource variant corresponding to the given resource.
-	 * The depth
+	 * Fetch the resource variant corresponding to the given resource. The depth
 	 * parameter indicates the depth of the refresh operation and also indicates the
 	 * depth to which the resource variant's desendants will be traversed. 
 	 * This method may prefetch the descendants to the provided depth
 	 * or may just return the variant handle corresponding to the given 
 	 * local resource, in which case
-	 * the descendant variants will be fetched by <code>fecthMembers(IResourceVariant, IProgressMonitor)</code>.
+	 * the descendant variants will be fetched by <code>fetchMembers(IResourceVariant, IProgressMonitor)</code>.
 	 * @param resource the local resource
 	 * @param depth the depth of the refresh  (one of <code>IResource.DEPTH_ZERO</code>,
 	 * <code>IResource.DEPTH_ONE</code>, or <code>IResource.DEPTH_INFINITE</code>)
@@ -151,11 +149,12 @@ public abstract class AbstractResourceVariantTree implements IResourceVariantTre
 	 * @return the resource variant corresponding to the given local resource
 	 */
 	protected abstract IResourceVariant fetchVariant(IResource resource, int depth, IProgressMonitor monitor) throws TeamException;
+
 	/**
 	 * Method that is invoked during collection to let subclasses know which members
 	 * were collected for the given resource. Implementors should purge any cached 
 	 * state for children of the local resource that are no longer members. Any such resources
-	 * should be returned.
+	 * should be returned to allow clients to clear any state they maintain for those resources.
 	 * @param local the local resource
 	 * @param members the collected members
 	 * @return any resources that were previously collected whose state has been flushed
@@ -166,9 +165,8 @@ public abstract class AbstractResourceVariantTree implements IResourceVariantTre
 
 	/**
 	 * Set the variant associated with the local resource to the newly fetched resource
-	 * variant. 
-	 * This method is invoked during change collection and should return whether
-	 * the variant associated with the lcoal resource has changed
+	 * variant. This method is invoked during change collection and should return whether
+	 * the variant associated with the local resource has changed
 	 * @param local the local resource
 	 * @param remote the newly fetched resoure variant
 	 * @return <code>true</code> if the resource variant changed
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/CachedResourceVariant.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/CachedResourceVariant.java
index 1f2be349e..e9e25fa15 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/CachedResourceVariant.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/CachedResourceVariant.java
@@ -32,12 +32,12 @@ import org.eclipse.team.internal.core.TeamPlugin;
 /**
  * A resource variant is a partial implementation of a remote resource
  * whose contents and handle are cached locally. It is assumed that a
- * resource varant is an immutable version or revision of a resource.
+ * resource variant is an immutable version or revision of a resource.
  * Therefore, once the contents are cached they cannot be replaced.
  * However, the cached handle can be replaced to allow clients to
  * cache addition state or properties for a resource variant.
  * <p>
- * Overriding subclasses need to provide a cache Id for al there resource variants
+ * Overriding subclasses need to provide a cache Id for all their resource variants
  * and a cache path for each resource variant that uniquely identifies it. In addition,
  * they must implement <code>fetchContents</code> to retrieve the contents of the
  * resource variant and then call <code>setContents</code> to place these contents in the cache.
@@ -47,9 +47,14 @@ import org.eclipse.team.internal.core.TeamPlugin;
  * cache additional resource variant properties such as author, comment, etc.
  * </p>
  * <p>
+ * The <code>IStorage</code> instance returned by this class will be 
+ * an {@link org.eclipse.core.resources.IEncodedStorage}.
+ * <p>
  * The cache in which the resource variants reside will occasionally clear
  * cached entries if they have not been accessed for a certain amount of time.
  * </p>
+ * 
+ * @since 3.0
  */
 public abstract class CachedResourceVariant extends PlatformObject implements IResourceVariant {
 	
@@ -99,7 +104,7 @@ public abstract class CachedResourceVariant extends PlatformObject implements IR
 	}
 	
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.core.synchronize.IRemoteResource#getStorage(org.eclipse.core.runtime.IProgressMonitor)
+	 * @see org.eclipse.team.core.variants.IResourceVariant#getStorage(org.eclipse.core.runtime.IProgressMonitor)
 	 */
 	public IStorage getStorage(IProgressMonitor monitor) throws TeamException {
 		if (isContainer()) return null;
@@ -129,7 +134,9 @@ public abstract class CachedResourceVariant extends PlatformObject implements IR
 
 	/**
 	 * This method should be invoked by subclasses from within their <code>fetchContents</code>
-	 * method in order to cache the contents for this resource variant.
+	 * method in order to cache the contents for this resource variant. 
+	 * <p>
+	 * This method is not intended to be overridden by clients.
 	 * @param stream the stream containing the contents of the resource variant
 	 * @param monitor a progress monitor
 	 * @throws TeamException
@@ -150,7 +157,9 @@ public abstract class CachedResourceVariant extends PlatformObject implements IR
 	 * This method will return <code>false</code> even if the contents are currently
 	 * being cached by another thread. The consequence of this is that the contents
 	 * may be fetched twice in the rare case where two threads request the same contents
-	 * at the same time. For containers, this method will always return <code>false</code>.
+	 * concurrently. For containers, this method will always return <code>false</code>.
+	 * <p>
+	 * This method is not intended to be overridden by clients.
 	 */
 	protected boolean isContentsCached() {
 		if (isContainer() || !isHandleCached()) {
@@ -164,6 +173,8 @@ public abstract class CachedResourceVariant extends PlatformObject implements IR
 	 * Return the cached contents for this resource variant or <code>null</code>
 	 * if the contents have not been cached.
 	 * For containers, this method will always return <code>null</code>.
+	 * <p>
+	 * This method is not intended to be overridden by clients.
 	 * @return the cached contents or <code>null</code>
 	 * @throws TeamException
 	 */
@@ -179,6 +190,8 @@ public abstract class CachedResourceVariant extends PlatformObject implements IR
 	 * cached contents can be retrieved from any handle to a resource variant whose
 	 * cache path (as returned by <code>getCachePath()</code>) match but other
 	 * state information may only be accessible from the cached copy.
+	 * <p>
+	 * This method is not intended to be overridden by clients.
 	 * @return whether the variant is cached
 	 */
 	protected boolean isHandleCached() {
@@ -233,6 +246,8 @@ public abstract class CachedResourceVariant extends PlatformObject implements IR
 	 * one. If there isn't one, then <code>null</code> is returned.
 	 * If there is no cached handle and one is desired, then <code>cacheHandle()</code>
 	 * should be called.
+	 * <p>
+	 * This method is not intended to be overridden by clients.
 	 * @return a cached copy of this resource variant or <code>null</code>
 	 */
 	protected CachedResourceVariant getCachedHandle() {
@@ -250,6 +265,8 @@ public abstract class CachedResourceVariant extends PlatformObject implements IR
 	 * resource version (or revision). The ability to replace the handle itself
 	 * is provided so that additional state may be cached before or after the contents
 	 * are fetched.
+	 * <p>
+	 * This method is not intended to be overridden by clients.
 	 */
 	protected void cacheHandle() {
 		getCache().add(getCachePath(), this);
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariant.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariant.java
index 76204f61a..fd8a7d928 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariant.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariant.java
@@ -28,14 +28,14 @@ public interface IResourceVariant {
 	 * Answers the name of the remote resource. The name may be
 	 * displayed to the user.
 	 * 
-	 * @return name of the subscriber resource.
+	 * @return name of the resource variant.
 	 */
 	public String getName();
 	
 	/**
 	 * Answers if the remote resource may have children.
 	 * 
-	 * @return <code>true</code> if the remote element may have children and 
+	 * @return <code>true</code> if the remote resource may have children and 
 	 * <code>false</code> otherwise.
 	 */
 	public boolean isContainer();
@@ -48,6 +48,10 @@ public interface IResourceVariant {
 	 * argument to this method). Implementations of this method should
 	 * ensure that the resulting <code>IStorage</code> is accessing locally cached contents and is not
 	 * contacting the server.
+	 * <p>
+	 * The returned storage object may be an instance of (@link org.eclipse.core.resources.IEncodedStorage}
+	 * in which case clients can determine the character encoding of the contents.
+	 * 
 	 * @return an <code>IStorage</code> that provides access to the contents of 
 	 * the remote resource or <code>null</code> if the remote resource is a container.
 	 */
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariantComparator.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariantComparator.java
index aba626bb7..b4b01ed5d 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariantComparator.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariantComparator.java
@@ -51,7 +51,7 @@ public interface IResourceVariantComparator {
 	public boolean compare(IResourceVariant base, IResourceVariant remote);
 
 	/**
-	 * Answers <code>true</code> if the base tree is maintained by this
+	 * Answers <code>true</code> if the base tree is maintained by this comparator's
 	 * subscriber. If the base tree is not considered than the subscriber can
 	 * be considered as not supported three-way comparisons. Instead
 	 * comparisons are made between the local and remote only without
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariantTree.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariantTree.java
index ff383c6f0..c75834207 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariantTree.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/IResourceVariantTree.java
@@ -21,6 +21,8 @@ import org.eclipse.team.core.TeamException;
  * clients may subclass {@link AbstractResourceVariantTree} or {@link ResourceVariantTree}.
  * </p>
  * 
+ * @see AbstractResourceVariantTree
+ * @see ResourceVariantTree
  * @since 3.0
  */
 public interface IResourceVariantTree {
@@ -35,7 +37,7 @@ public interface IResourceVariantTree {
 	/**
 	 * Returns the members of the local resource that have resource variants in this tree.
 	 * The members may or may not exist locally. The resource variants corresponding to the
-	 * memebers can be retrieved using <code>getResourceVariant(IResource)</code>.
+	 * members can be retrieved using <code>getResourceVariant(IResource)</code>.
 	 * @param resource the local resource
 	 * @return the members of the local resource for which this tree contains resource variants
 	 * @throws TeamException
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ISynchronizerChangeListener.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ISynchronizerChangeListener.java
index 746b7868c..ed29b0825 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ISynchronizerChangeListener.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ISynchronizerChangeListener.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials 
  * are made available under the terms of the Common Public License v1.0
  * which accompanies this distribution, and is available at
@@ -15,11 +15,15 @@ import org.eclipse.core.resources.IResource;
 /**
  * Listener that can receive notification from a <code>ThreeWaySynchronizer</code>
  * when the synchronization state of one or more resources has changed.
+ * @see ThreeWaySynchronizer
+ * @since 3.0
  */
 public interface ISynchronizerChangeListener {
 	
 	/**
 	 * Notification of synchronization state changes for the given resources.
+	 * Clients must query the <code>ThreeWaySynchronizer</code> that generated
+	 * this event to determine the new synchronization state.
 	 * @param resources the resources whose synchronization state has changed
 	 */
 	public void syncStateChanged(IResource[] resources);
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/PersistantResourceVariantByteStore.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/PersistantResourceVariantByteStore.java
index ff4af896a..681e419c0 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/PersistantResourceVariantByteStore.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/PersistantResourceVariantByteStore.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials 
  * are made available under the terms of the Common Public License v1.0
  * which accompanies this distribution, and is available at
@@ -48,7 +48,7 @@ public class PersistantResourceVariantByteStore extends ResourceVariantByteStore
 	}
 	
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#dispose()
+	 * @see org.eclipse.team.core.variants.ResourceVariantByteStore#dispose()
 	 */
 	public void dispose() {
 		getSynchronizer().remove(getSyncName());
@@ -63,7 +63,7 @@ public class PersistantResourceVariantByteStore extends ResourceVariantByteStore
 	}
 
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#getBytes(org.eclipse.core.resources.IResource)
+	 * @see org.eclipse.team.core.variants.ResourceVariantByteStore#getBytes(org.eclipse.core.resources.IResource)
 	 */
 	public byte[] getBytes(IResource resource) throws TeamException {
 		byte[] syncBytes = internalGetSyncBytes(resource);
@@ -75,7 +75,7 @@ public class PersistantResourceVariantByteStore extends ResourceVariantByteStore
 	}
 	
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#setBytes(org.eclipse.core.resources.IResource, byte[])
+	 * @see org.eclipse.team.core.variants.ResourceVariantByteStore#setBytes(org.eclipse.core.resources.IResource, byte[])
 	 */
 	public boolean setBytes(IResource resource, byte[] bytes) throws TeamException {
 		Assert.isNotNull(bytes);
@@ -90,7 +90,7 @@ public class PersistantResourceVariantByteStore extends ResourceVariantByteStore
 	}
 
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#removeBytes(org.eclipse.core.resources.IResource, int)
+	 * @see org.eclipse.team.core.variants.ResourceVariantByteStore#flushBytes(org.eclipse.core.resources.IResource, int)
 	 */
 	public boolean flushBytes(IResource resource, int depth) throws TeamException {
 		if (resource.exists() || resource.isPhantom()) {
@@ -106,8 +106,14 @@ public class PersistantResourceVariantByteStore extends ResourceVariantByteStore
 		return false;
 	}
 	
-	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#isVariantKnown(org.eclipse.core.resources.IResource)
+	/**
+	 * Return whether the resource variant state for this resource is known.
+	 * This is used to differentiate the case where a resource variant has never been fetched
+	 * from the case where the resource variant is known to not exist. In the later
+	 * case, this method returns <code>true</code> while <code>getBytes</code> returns <code>null</code>
+	 * @param resource the local resource
+	 * @return whether the resource variant state for this resource is known
+	 * @throws TeamException
 	 */
 	public boolean isVariantKnown(IResource resource) throws TeamException {
 		return internalGetSyncBytes(resource) != null;
@@ -116,8 +122,8 @@ public class PersistantResourceVariantByteStore extends ResourceVariantByteStore
 	/**
 	 * This method should be invoked by a client to indicate that it is known that 
 	 * there is no remote resource associated with the local resource. After this method
-	 * is invoked, <code>isRemoteKnown(resource)</code> will return <code>true</code> and
-	 * <code>getSyncBytes(resource)</code> will return <code>null</code>.
+	 * is invoked, <code>isVariantKnown(resource)</code> will return <code>true</code> and
+	 * <code>getBytes(resource)</code> will return <code>null</code>.
 	 * @return <code>true</code> if this changes the remote sync bytes
 	 */
 	public boolean deleteBytes(IResource resource) throws TeamException {
@@ -125,7 +131,7 @@ public class PersistantResourceVariantByteStore extends ResourceVariantByteStore
 	}
 
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#members(org.eclipse.core.resources.IResource)
+	 * @see org.eclipse.team.core.variants.ResourceVariantByteStore#members(org.eclipse.core.resources.IResource)
 	 */
 	public IResource[] members(IResource resource) throws TeamException {
 		if(resource.getType() == IResource.FILE) {
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantByteStore.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantByteStore.java
index 7caf8f09e..82ebe51e5 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantByteStore.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantByteStore.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials 
  * are made available under the terms of the Common Public License v1.0
  * which accompanies this distribution, and is available at
@@ -25,9 +25,8 @@ import org.eclipse.team.core.TeamException;
  * reponsibility of the client of this API to cache enough bytes to meaningfully identify
  * a resource variant (and possibly create an {@link IResourceVariant} handle from them).
  * <p>
- * The bytes for
- * a resource variant are accessed using the local handle that corresponds to the 
- * resource variant (using the <code>getSyncInfo</code> method). 
+ * The bytes for a resource variant are accessed using the local <code>IResource</code> handle 
+ * that corresponds to the resource variant (using the <code>getBytes</code> method). 
  * The potential children of a resource variant are also accessed
  * by using the local handle that corresponds to the resource variant 
  * (using the <code>members</code> method).
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantTree.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantTree.java
index 8a496e514..afde6ead2 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantTree.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantTree.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials 
  * are made available under the terms of the Common Public License v1.0
  * which accompanies this distribution, and is available at
@@ -29,36 +29,38 @@ public abstract class ResourceVariantTree extends AbstractResourceVariantTree {
 	
 	private ResourceVariantByteStore store;
 
+	/**
+	 * Create a resource variant tree that uses the provided byte store to
+	 * cache the resource variant bytes.
+	 * @param store the resource variant byte store used to cahe resource variants
+	 */
 	protected ResourceVariantTree(ResourceVariantByteStore store) {
 		this.store = store;
 	}
 	
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.IResourceVariantTree#members(org.eclipse.core.resources.IResource)
+	 * @see org.eclipse.team.core.variants.IResourceVariantTree#members(org.eclipse.core.resources.IResource)
 	 */
 	public IResource[] members(IResource resource) throws TeamException {
 		return getByteStore().members(resource);
 	}
 	
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.IResourceVariantTree#hasResourceVariant(org.eclipse.core.resources.IResource)
+	 * @see org.eclipse.team.core.variants.IResourceVariantTree#hasResourceVariant(org.eclipse.core.resources.IResource)
 	 */
 	public boolean hasResourceVariant(IResource resource) throws TeamException {
 		return getByteStore().getBytes(resource) != null;
 	}
 	
-	/**
-	 * Flush any variants for the given resource to the depth specified.
-	 * @param resource the local resource
-	 * @param depth the depth of the flush
-	 * @throws TeamException
+	/* (non-Javadoc)
+	 * @see org.eclipse.team.core.variants.IResourceVariantTree#flushVariants(org.eclipse.core.resources.IResource, int)
 	 */
 	public void flushVariants(IResource resource, int depth) throws TeamException {
 		getByteStore().flushBytes(resource, depth);
 	}
 	
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.AbstractResourceVariantTree#setVariant(org.eclipse.core.resources.IResource, org.eclipse.team.core.synchronize.IResourceVariant)
+	 * @see org.eclipse.team.core.variants.AbstractResourceVariantTree#setVariant(org.eclipse.core.resources.IResource, org.eclipse.team.core.variants.IResourceVariant)
 	 */
 	protected boolean setVariant(IResource local, IResourceVariant remote) throws TeamException {
 		ResourceVariantByteStore cache = getByteStore();
@@ -72,12 +74,13 @@ public abstract class ResourceVariantTree extends AbstractResourceVariantTree {
 		return changed;
 	}
 	
-
-	
 	/**
 	 * Get the byte store that is used to cache the serialization bytes
 	 * for the resource variants of this tree. A byte store is used
 	 * to reduce the memory footprint of the tree.
+	 * <p>
+	 * This method is not intended to be overriden by subclasses.
+	 * 
 	 * @return the resource variant tree that is being refreshed.
 	 */
 	protected ResourceVariantByteStore getByteStore() {
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantTreeSubscriber.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantTreeSubscriber.java
index 4d24dd84f..9fc328115 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantTreeSubscriber.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ResourceVariantTreeSubscriber.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials 
  * are made available under the terms of the Common Public License v1.0
  * which accompanies this distribution, and is available at
@@ -58,7 +58,7 @@ public abstract class ResourceVariantTreeSubscriber extends Subscriber {
 	}
 
 	/**
-	 * Method that creates an instance of SyncInfo for the provider local, base and remote
+	 * Method that creates an instance of SyncInfo for the provided local, base and remote
 	 * resource variants.
 	 * Can be overiden by subclasses.
 	 * @param local the local resource
@@ -111,7 +111,7 @@ public abstract class ResourceVariantTreeSubscriber extends Subscriber {
 	}
 
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.core.sync.ISyncTreeSubscriber#refresh(org.eclipse.core.resources.IResource[], int, org.eclipse.core.runtime.IProgressMonitor)
+	 * @see org.eclipse.team.core.subscribers.Subscriber#refresh(org.eclipse.core.resources.IResource[], int, org.eclipse.core.runtime.IProgressMonitor)
 	 */
 	public void refresh(IResource[] resources, int depth, IProgressMonitor monitor) throws TeamException {
 		monitor = Policy.monitorFor(monitor);
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/SessionResourceVariantByteStore.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/SessionResourceVariantByteStore.java
index d49e46c9e..dfffe949c 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/SessionResourceVariantByteStore.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/SessionResourceVariantByteStore.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials 
  * are made available under the terms of the Common Public License v1.0
  * which accompanies this distribution, and is available at
@@ -33,14 +33,14 @@ public class SessionResourceVariantByteStore extends ResourceVariantByteStore {
 	private Map syncBytesCache = new HashMap();
 
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#setVariantDoesNotExist(org.eclipse.core.resources.IResource)
+	 * @see org.eclipse.team.core.variants.ResourceVariantByteStore#deleteBytes(org.eclipse.core.resources.IResource)
 	 */
 	public boolean deleteBytes(IResource resource) throws TeamException {
 		return flushBytes(resource, IResource.DEPTH_ZERO);
 	}
 	
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#dispose()
+	 * @see org.eclipse.team.core.variants.ResourceVariantByteStore#dispose()
 	 */
 	public void dispose() {
 		syncBytesCache.clear();
@@ -48,7 +48,7 @@ public class SessionResourceVariantByteStore extends ResourceVariantByteStore {
 	}
 
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#removeBytes(org.eclipse.core.resources.IResource, int)
+	 * @see org.eclipse.team.core.variants.ResourceVariantByteStore#flushBytes(org.eclipse.core.resources.IResource, int)
 	 */
 	public boolean flushBytes(IResource resource, int depth) throws TeamException {
 		if (getSyncBytesCache().containsKey(resource)) {
@@ -67,7 +67,7 @@ public class SessionResourceVariantByteStore extends ResourceVariantByteStore {
 	}
 
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#getBytes(org.eclipse.core.resources.IResource)
+	 * @see org.eclipse.team.core.variants.ResourceVariantByteStore#getBytes(org.eclipse.core.resources.IResource)
 	 */
 	public byte[] getBytes(IResource resource) throws TeamException {
 		byte[] syncBytes = internalGetSyncBytes(resource);
@@ -87,7 +87,7 @@ public class SessionResourceVariantByteStore extends ResourceVariantByteStore {
 	}
 
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#members(org.eclipse.core.resources.IResource)
+	 * @see org.eclipse.team.core.variants.ResourceVariantByteStore#members(org.eclipse.core.resources.IResource)
 	 */
 	public IResource[] members(IResource resource) {
 		List members = (List)membersCache.get(resource);
@@ -97,9 +97,8 @@ public class SessionResourceVariantByteStore extends ResourceVariantByteStore {
 		return (IResource[]) members.toArray(new IResource[members.size()]);
 	}
 
-	/*
-	 *  (non-Javadoc)
-	 * @see org.eclipse.team.internal.core.subscribers.caches.ResourceVariantByteStore#setBytes(org.eclipse.core.resources.IResource, byte[])
+	/* (non-Javadoc)
+	 * @see org.eclipse.team.core.variants.ResourceVariantByteStore#setBytes(org.eclipse.core.resources.IResource, byte[])
 	 */
 	public boolean setBytes(IResource resource, byte[] bytes) throws TeamException {
 		Assert.isNotNull(bytes);
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWayRemoteTree.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWayRemoteTree.java
index fafe387a2..bd84b1903 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWayRemoteTree.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWayRemoteTree.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials 
  * are made available under the terms of the Common Public License v1.0
  * which accompanies this distribution, and is available at
@@ -18,7 +18,7 @@ import org.eclipse.team.core.TeamException;
 
 /**
  * A resource variant tree that caches and obtains its bytes from the remote slot
- * in a three-way synchronizer. Clients must subclass to provide remote recource
+ * in a three-way synchronizer. Clients must subclass to provide remote resource
  * variant refresh functionality.
  * 
  * @see ThreeWaySubscriber
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWayResourceComparator.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWayResourceComparator.java
index b152f44e8..bc8955118 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWayResourceComparator.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWayResourceComparator.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials 
  * are made available under the terms of the Common Public License v1.0
  * which accompanies this distribution, and is available at
@@ -16,7 +16,12 @@ import org.eclipse.team.internal.core.TeamPlugin;
 
 /**
  * A resource comparator that uses the <code>ThreeWaySynchronizer</code>
- * to compare local resources to their resource variants.
+ * to compare local resources to their resource variants. The local state
+ * is determined using the local modification state and the remote state
+ * is determined by comparing the base bytes to the remote bytes obtained
+ * from the synchronizer.
+ * 
+ * @since 3.0
  */
 public class ThreeWayResourceComparator implements IResourceVariantComparator {
 	
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWaySubscriber.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWaySubscriber.java
index 66812d594..390ce4a31 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWaySubscriber.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWaySubscriber.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials 
  * are made available under the terms of the Common Public License v1.0
  * which accompanies this distribution, and is available at
@@ -22,7 +22,16 @@ import org.eclipse.team.internal.core.subscribers.ThreeWayBaseTree;
 /**
  * A resource variant tree subscriber whose trees use an underlying
  * <code>ThreeWaySycnrhonizer</code> to store and manage the
- * synchronization state for the local workspace.
+ * synchronization state for the local workspace. Subclasses need to
+ * provide a subclass of <code>ThreeWayRemoteTree</code> and a method
+ * to create resource variant handles from the bytes cached in the
+ * <code>ThreeWaySynchronizer</code>.
+ * 
+ * @see ThreeWaySynchronizer
+ * @see ThreeWayRemoteTree
+ * @see CachedResourceVariant
+ * 
+ * @since 3.0
  */
 public abstract class ThreeWaySubscriber extends ResourceVariantTreeSubscriber implements ISynchronizerChangeListener {
 	
@@ -71,7 +80,7 @@ public abstract class ThreeWaySubscriber extends ResourceVariantTreeSubscriber i
 	}
 	
 	/* (non-Javadoc)
-	 * @see org.eclipse.team.internal.target.subscriber.ISynchronizerChangeListener#syncStateChanged(org.eclipse.core.resources.IResource[])
+	 * @see org.eclipse.team.core.variants.ISynchronizerChangeListener#syncStateChanged(org.eclipse.core.resources.IResource[])
 	 */
 	public void syncStateChanged(IResource[] resources) {
 		fireTeamResourceChange(SubscriberChangeEvent.asSyncChangedDeltas(this, resources));
diff --git a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWaySynchronizer.java b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWaySynchronizer.java
index 62587922d..0e05c9019 100644
--- a/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWaySynchronizer.java
+++ b/bundles/org.eclipse.team.core/src/org/eclipse/team/core/variants/ThreeWaySynchronizer.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2000, 2003 IBM Corporation and others.
+ * Copyright (c) 2000, 2004 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials 
  * are made available under the terms of the Common Public License v1.0
  * which accompanies this distribution, and is available at