[cleanup] javadoc

rse/plugins/org.eclipse.rse.ui/filters/org/eclipse/rse/filters/SystemFilterPoolReferenceManager.java

@@ -44,6 +44,9 @@ import org.eclipse.rse.internal.references.SystemPersistableReferenceManager;
  * a filter pool. This class builds on the parent class SystemPersistableReferenceManager,
  * offering convenience versions of the parent methods that are typed to the
  * classes in the filters framework.
+ * 
+ * There will be one of these instantiated for a subsystem. Filter pool references can 
+ * be moved within a subsystem and this manager provides that function as well.
  */
 /** 
  * @lastgen class SystemFilterPoolReferenceManagerImpl extends SystemPersistableReferenceManagerImpl implements SystemFilterPoolReferenceManager, SystemPersistableReferenceManager {}
@@ -72,12 +75,12 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	}
 
 	/**
-	 * Create a SystemFilterPoolReferenceManager instance.
+	 * A factory method to create a SystemFilterPoolReferenceManager instance.
 	 * @param caller Objects which instantiate this class should implement the
 	 *   SystemFilterPoolReferenceManagerProvider interface, and pass "this" for this parameter.
 	 *   Given any filter framework object, it is possible to retrieve the caller's
 	 *   object via the getProvider method call.
-	 * @param relatedPoolManagers The managers that owns the master list of filter pools that 
+	 * @param relatedPoolManagerProvider The managers that owns the master list of filter pools that 
 	 *   this manager will contain references to.
 	 * @param mgrFolder the folder that will hold the persisted file. This is used when
 	 *   the save policy is SAVE_POLICY_ONE_FILE_PER_MANAGER. For SAVE_POLICY_NONE, this
@@ -93,6 +96,7 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	 *   </ul> 
 	 * @param namingPolicy The names to use for file and folders when persisting to disk. Pass
 	 *     null to just use the defaults, or if using SAVE_POLICY_NONE.
+	 * @return a filter pool reference manager
 	 */
 	public static ISystemFilterPoolReferenceManager createSystemFilterPoolReferenceManager(ISystemFilterPoolReferenceManagerProvider caller,
 			ISystemFilterPoolManagerProvider relatedPoolManagerProvider, IFolder mgrFolder, String name, int savePolicy, IRSEFilterNamingPolicy namingPolicy) {
@@ -119,11 +123,9 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 
 	/*
 	 * Private helper method.
-	 * Uses MOF to create an instance of this class.
 	 */
 	protected static SystemFilterPoolReferenceManager createManager() {
 		ISystemFilterPoolReferenceManager mgr = new SystemFilterPoolReferenceManager();
-		// FIXME SystemFilterImpl.initMOF().createSystemFilterPoolReferenceManager();
 		return (SystemFilterPoolReferenceManager) mgr;
 	}
 
@@ -160,50 +162,41 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	// ------------------------------------------------------------
 	/**
 	 * Set the associated master pool manager provider. Note the provider
-	 *  typically manages multiple pool managers and we manage references
+	 * typically manages multiple pool managers and we manage references
-	 *  across those.
+	 * across those.
+	 * @param poolMgrProvider the factory (provider) for the filter pool managers that this 
+	 * reference manager provides services to
 	 */
 	public void setSystemFilterPoolManagerProvider(ISystemFilterPoolManagerProvider poolMgrProvider) {
 		this.poolMgrProvider = poolMgrProvider;
 	}
 
 	/**
-	 * Get the associated master pool manager provider. Note the provider
+	 * @return the associated master pool manager provider. Note the provider
-	 *  typically manages multiple pool managers and we manage references
+	 * typically manages multiple pool managers and we manage references
-	 *  across those.
+	 * across those.
 	 */
 	public ISystemFilterPoolManagerProvider getSystemFilterPoolManagerProvider() {
 		return poolMgrProvider;
 	}
 
-	/*
-	 * Set the managers of the master list of filter pools, from which
-	 *  objects in this list reference.
-	 *
-	 public void setSystemFilterPoolManagers(SystemFilterPoolManager[] mgrs)
-	 {
-	 this.poolMgrs = mgrs;
-	 }*/
-
 	/**
-	 * Get the managers of the master list of filter pools, from which
+	 * @return the managers of the master list of filter pools, from which
-	 *  objects in this list reference.
+	 * objects in this list reference.
 	 */
 	public ISystemFilterPoolManager[] getSystemFilterPoolManagers() {
-		//return poolMgrs;
 		return poolMgrProvider.getSystemFilterPoolManagers();
 	}
 
 	/**
-	 * Get the managers of the master list of filter pools, from which
+	 * @return the managers of the master list of filter pools, from which
-	 *  objects in this list reference, but which are not in the list of
+	 * objects in this list reference, but which are not in the list of
-	 *  managers our pool manager supplier gives us. That is, these are
+	 * managers our pool manager supplier gives us. That is, these are
-	 *  references to filter pools outside the expected list.
+	 * references to filter pools outside the expected list.
 	 */
 	public ISystemFilterPoolManager[] getAdditionalSystemFilterPoolManagers() {
 		ISystemFilterPoolManager[] poolMgrs = getSystemFilterPoolManagers();
 		Vector v = new Vector();
-
 		ISystemFilterPoolReference[] fpRefs = getSystemFilterPoolReferences();
 		for (int idx = 0; idx < fpRefs.length; idx++) {
 			ISystemFilterPool pool = fpRefs[idx].getReferencedFilterPool();
@@ -224,6 +217,12 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 		return additionalMgrs;
 	}
 
+	/**
+	 * Look for a pool manager in an array of pool managers.
+	 * @param mgrs the array in which to look
+	 * @param mgr the item to look for
+	 * @return true if the manager was found
+	 */
 	private boolean managerExists(ISystemFilterPoolManager[] mgrs, ISystemFilterPoolManager mgr) {
 		boolean match = false;
 		for (int idx = 0; !match && (idx < mgrs.length); idx++)
@@ -233,22 +232,24 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 
 	/**
 	 * Set the default manager of the master list of filter pools, from which
-	 *  objects in this list reference.
+	 * objects in this list reference.
+	 * @param mgr the filter pool manager that is the default pool manager.
 	 */
 	public void setDefaultSystemFilterPoolManager(ISystemFilterPoolManager mgr) {
 		defaultPoolMgr = mgr;
 	}
 
 	/**
-	 * Get the default manager of the master list of filter pools, from which
+	 * @return the default manager of the master list of filter pools, from which
-	 *  objects in this list reference.
+	 * objects in this list reference.
 	 */
 	public ISystemFilterPoolManager getDefaultSystemFilterPoolManager() {
 		return defaultPoolMgr;
 	}
 
 	/**
-	 * Get the object which instantiated this instance of the filter pool reference manager.
+	 * @return the object (the "provider" or factory) which instantiated 
+	 * this instance of the filter pool reference manager.
 	 * This is also available from any filter reference framework object.
 	 */
 	public ISystemFilterPoolReferenceManagerProvider getProvider() {
@@ -259,13 +260,15 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	 * Set the object which instantiated this instance of the filter pool reference manager.
 	 * This makes it available to retrieve from any filter reference framework object,
 	 * via the ubiquitous getProvider interface method.
+	 * @param caller the factory that created this instance.
 	 */
 	public void setProvider(ISystemFilterPoolReferenceManagerProvider caller) {
 		this.caller = caller;
 	}
 
 	/**
-	 * Turn off callbacks to the provider until turned on again.
+	 * Turn callbacks to the provider either off or on.
+	 * @param fireEvents true if events are to be fired to the provider object, false if not.
 	 */
 	public void setProviderEventNotification(boolean fireEvents) {
 		this.fireEvents = fireEvents;
@@ -274,6 +277,7 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	/**
 	 * Set the naming policy used when saving data to disk.
 	 * @see org.eclipse.rse.core.filters.IRSEFilterNamingPolicy
+	 * @param namingPolicy the naming policy - no longer used.
 	 */
 	public void setNamingPolicy(IRSEFilterNamingPolicy namingPolicy) {
 		this.namingPolicy = namingPolicy;
@@ -282,6 +286,7 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	/**
 	 * Get the naming policy currently used when saving data to disk.
 	 * @see org.eclipse.rse.core.filters.IRSEFilterNamingPolicy
+	 * @return the naming policy - no longer used.
 	 */
 	public IRSEFilterNamingPolicy getNamingPolicy() {
 		return namingPolicy;
@@ -289,13 +294,14 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 
 	/**
 	 * This is to set transient data that is subsequently queryable.
+	 * @param data the data associated with this pool reference manager.
 	 */
 	public void setSystemFilterPoolReferenceManagerData(Object data) {
 		this.mgrData = data;
 	}
 
 	/**
-	 * Return transient data set via setFilterPoolData.
+	 * @return transient data set via setFilterPoolData.
 	 */
 	public Object getSystemFilterPoolReferenceManagerData() {
 		return mgrData;
@@ -305,12 +311,10 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	 * Set the name. This is an override of mof-generated method
 	 * in order to potentially rename the disk file for a save
 	 * policy of SAVE_POLICY_ONE_FILE_PER_MANAGER.
+	 * No longer used.
+	 * @param name the name of this reference manager.
 	 */
 	public void setName(String name) {
-		/*
-		 * DWD Setting a name should schedule a save. Is this the same as a rename?
-		 */
-		//    	String oldName = getName();
 		if (savePolicy == ISystemFilterSavePolicies.SAVE_POLICY_ONE_FILE_PER_MANAGER) {
 			IFile file = getResourceHelpers().getFile(getFolder(), getSaveFileName());
 			super.setName(name);
@@ -341,7 +345,7 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	}
 
 	/**
-	 * Return array of SystemFilterPoolReference objects.
+	 * @return array of SystemFilterPoolReference objects.
 	 * Result will never be null, although it may be an array of length zero.
 	 */
 	public ISystemFilterPoolReference[] getSystemFilterPoolReferences() {
@@ -357,9 +361,8 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	}
 
 	/**
-	 * In one shot, set the filter pool references
+	 * In one shot, set the filter pool references. Calls back to inform provider.
-	 * <p>Calls back to inform provider
+	 * @param filterPoolReferences an array of filter pool reference objects to set the list to.
-	 * @param array of filter pool reference objects to set the list to.
 	 * @param deReference true to first de-reference all objects in the existing list.
 	 */
 	public void setSystemFilterPoolReferences(ISystemFilterPoolReference[] filterPoolReferences, boolean deReference) {
@@ -385,7 +388,6 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	 * must be added to the managed lists by the caller.
 	 * That will be attempted to be resolved on first use.
 	 */
-	// DWD working
 	private ISystemFilterPoolReference createSystemFilterPoolReference(ISystemFilterPoolManager filterPoolManager, String filterPoolName) {
 		ISystemFilterPoolReference filterPoolReference = new SystemFilterPoolReference(filterPoolManager, filterPoolName);
 		invalidateFilterPoolReferencesCache();
@@ -394,11 +396,12 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 
 	/**
 	 * Add a filter pool referencing object to the list. 
+	 * @param filterPoolReference a reference to add to this manager
 	 * @return the new count of referencing objects
 	 */
 	public int addSystemFilterPoolReference(ISystemFilterPoolReference filterPoolReference) {
 		int count = addReferencingObject(filterPoolReference);
-		filterPoolReference.setParentReferenceManager(this); // DWD - should be done in the addReferencingObject method
+		filterPoolReference.setParentReferenceManager(this); // DWD - should be done in the addReferencingObject method?
 		invalidateFilterPoolReferencesCache();
 		quietSave();
 		return count;
@@ -406,18 +409,19 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 
 	/**
 	 * Reset the filter pool a reference points to. Called on a move-filter-pool operation
+	 * @param filterPoolReference the reference to fix up
+	 * @param newPool the new pool to reference
 	 */
 	public void resetSystemFilterPoolReference(ISystemFilterPoolReference filterPoolReference, ISystemFilterPool newPool) {
 		filterPoolReference.removeReference();
 		filterPoolReference.setReferencedObject(newPool);
 		if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferenceReset(filterPoolReference);
 		quietSave();
-		// don't think we need to invalidate the cache
 	}
 
 	/**
 	 * Remove a filter pool referencing object from the list.
-	 * @param filterPool Reference the reference to remove
+	 * @param filterPoolReference the reference to remove
 	 * @param deReference true if we want to dereference the referenced object (call removeReference on it)
 	 * @return the new count of referencing objects
 	 */
@@ -427,37 +431,39 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 			count = super.removeReferencingObject(filterPoolReference);
 		else
 			count = super.removeAndDeReferenceReferencingObject(filterPoolReference);
-		filterPoolReference.setParentReferenceManager(null); // DWD should be done in remove
+		filterPoolReference.setParentReferenceManager(null); // DWD should be done in remove?
 		invalidateFilterPoolReferencesCache();
-		// callback to provider so they can fire events in their GUI
 		if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferenceDeleted(filterPoolReference);
 		quietSave();
 		return count;
 	}
 
 	/**
-	 * Return count of referenced filter pools
+	 * @return count of referenced filter pools
 	 */
 	public int getSystemFilterPoolReferenceCount() {
 		return super.getReferencingObjectCount();
 	}
 
 	/**
-	 * Return the zero-based position of a SystemFilterPoolReference object within this list
+	 * @param filterPoolRef the filter pool reference to search for
+	 * @return the zero-based position of the reference within this manager
 	 */
 	public int getSystemFilterPoolReferencePosition(ISystemFilterPoolReference filterPoolRef) {
 		return super.getReferencingObjectPosition(filterPoolRef);
 	}
 
 	/**
-	 * Move a given filter pool reference to a given zero-based location
+	 * Move a given filter pool reference to a given zero-based location.
-	 * Calls back to inform provider of the event
+	 * Calls back to inform provider of the event.
+	 * @param filterPoolRef the reference to move
+	 * @param pos the new position at which to move it. References at that position and beyond are
+	 * moved up in the list.
 	 */
 	public void moveSystemFilterPoolReference(ISystemFilterPoolReference filterPoolRef, int pos) {
 		int oldPos = super.getReferencingObjectPosition(filterPoolRef);
 		super.moveReferencingObjectPosition(pos, filterPoolRef);
 		invalidateFilterPoolReferencesCache();
-		// callback to provider so they can fire events in their GUI
 		if (!noSave) quietSave();
 		if (fireEvents && (caller != null) && !noEvents) {
 			ISystemFilterPoolReference[] refs = new ISystemFilterPoolReference[1];
@@ -469,11 +475,10 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	/**
 	 * Move existing filter pool references a given number of positions.
 	 * If the delta is negative, they are all moved up by the given amount. If 
-	 * positive, they are all moved down by the given amount.<p>
+	 * positive, they are all moved down by the given amount.
-	 * <p>
+	 * Calls back to inform provider.
-	 * Calls back to inform provider
 	 * @param filterPoolRefs Array of SystemFilterPoolReferences to move.
-	 * @param newPosition new zero-based position for the filter pool references.
+	 * @param delta the amount by which to move these references.
 	 */
 	public void moveSystemFilterPoolReferences(ISystemFilterPoolReference[] filterPoolRefs, int delta) {
 		int[] oldPositions = new int[filterPoolRefs.length];
@@ -496,7 +501,7 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	// Methods that work on FilterPool master objects
 	// ----------------------------------------------
 	/**
-	 * Return array of filter pools currently referenced by this manager
+	 * @return array of filter pools currently referenced by this manager.
 	 * Result will never be null, although it may be an array of length zero.
 	 */
 	public ISystemFilterPool[] getReferencedSystemFilterPools() {
@@ -508,7 +513,8 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	}
 
 	/**
-	 * Return true if the given filter pool has a referencing object in this list.
+	 * @param filterPool the filter pool to test to see if we have a reference to it
+	 * @return true if the given filter pool has a referencing object in this list.
 	 */
 	public boolean isSystemFilterPoolReferenced(ISystemFilterPool filterPool) {
 		return super.isReferenced(filterPool);
@@ -516,6 +522,7 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 
 	/**
 	 * Given a filter pool, locate the referencing object for it and return it.
+	 * @param filterPool the filter pool we are testing for a reference
 	 * @return the referencing object if found, else null
 	 */
 	public ISystemFilterPoolReference getReferenceToSystemFilterPool(ISystemFilterPool filterPool) {
@@ -531,12 +538,11 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 		filterPoolReference.setParentReferenceManager(this);
 		invalidateFilterPoolReferencesCache();
 		quietSave();
-		// callback to provider so they can fire events in their GUI
 		if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferenceCreated(filterPoolReference);
 		return filterPoolReference;
 	}
 
-	// DWD Working
+	// DWD Working - the method above and this one can be combined?
 	/* (non-Javadoc)
 	 * @see org.eclipse.rse.filters.ISystemFilterPoolReferenceManager#addReferenceToSystemFilterPool(org.eclipse.rse.filters.ISystemFilterPoolManager, java.lang.String)
 	 */
@@ -546,7 +552,6 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 		filterPoolReference.setParentReferenceManager(this);
 		invalidateFilterPoolReferencesCache();
 		quietSave();
-		// callback to provider so they can fire events in their GUI
 		if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferenceCreated(filterPoolReference);
 		return filterPoolReference;
 	}
@@ -554,15 +559,16 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	/**
 	 * Given a filter pool, locate the referencing object for it and remove it from the list.
 	 * Also removes that reference from the filterPool itself, and calls back to provider when done.
+	 * @param filterPool the filter pool whose references we are to remove
 	 * @return the new count of referencing objects
 	 */
 	public int removeReferenceToSystemFilterPool(ISystemFilterPool filterPool) {
 		ISystemFilterPoolReference filterPoolReference = getReferenceToSystemFilterPool(filterPool);
 		int newCount = 0;
 		if (filterPoolReference != null) {
-			filterPoolReference.removeReference(); // getReferencedFilterPool().removeReference(this)
+			filterPoolReference.removeReference();
 			newCount = removeReferencingObject(filterPoolReference);
-			filterPoolReference.setParentReferenceManager(null); // DWD should be done in removeReferencingObject
+			filterPoolReference.setParentReferenceManager(null); // DWD should be done in removeReferencingObject?
 			invalidateFilterPoolReferencesCache();
 			quietSave();
 			// callback to provider so they can fire events in their GUI
@@ -573,8 +579,9 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	}
 
 	/**
-	 * A reference filter pool has been renamed. Update our stored name...
+	 * A referenced filter pool has been renamed. Update our stored name.
-	 * <p> Calls back to inform provider
+	 * Calls back to inform provider.
+	 * @param pool the pool that has just been renamed
 	 */
 	public void renameReferenceToSystemFilterPool(ISystemFilterPool pool) {
 		ISystemFilterPoolReference poolRef = null;
@@ -587,14 +594,14 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 			poolRef.resetReferencedFilterPoolName(pool.getReferenceName());
 			invalidateFilterPoolReferencesCache();
 			quietSave();
-			// callback to provider so they can fire events in their GUI
 			if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferenceRenamed(poolRef, oldName);
 		}
 	}
 
 	/**
 	 * In one shot, set the filter pool references to new references to supplied filter pools.
-	 * @param array of filter pool objects to create references for
+	 * Calls back to provider.
+	 * @param filterPools of filter pool objects to create references for
 	 * @param deReference true to first de-reference all objects in the existing list.
 	 */
 	public void setSystemFilterPoolReferences(ISystemFilterPool[] filterPools, boolean deReference) {
@@ -602,18 +609,16 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 			super.removeAndDeReferenceAllReferencingObjects();
 		else
 			removeAllReferencingObjects();
-
 		// add current
 		if (filterPools != null) {
 			for (int idx = 0; idx < filterPools.length; idx++) {
 				//addReferenceToSystemFilterPool(filterPools[idx]);
 				ISystemFilterPoolReference filterPoolReference = createSystemFilterPoolReference(filterPools[idx]);
 				addReferencingObject(filterPoolReference);
-				filterPoolReference.setParentReferenceManager(this); // DWD should be done in addReferencingObject
+				filterPoolReference.setParentReferenceManager(this); // DWD should be done in addReferencingObject?
 			}
 			invalidateFilterPoolReferencesCache();
 			quietSave();
-			// callback to provider so they can fire events in their GUI
 			if (fireEvents && (caller != null)) caller.filterEventFilterPoolReferencesReset();
 		}
 	}
@@ -623,8 +628,11 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	// -------------------------
 	/**
 	 * Create a single filter refererence to a given filter. Needed when a filter
-	 *  is added to a pool, and the GUI is not showing pools but rather all filters
+	 * is added to a pool, and the UI is not showing pools but rather all filters
-	 *  in all pool references.
+	 * in all pool references.
+	 * @param subSystem the subsystem that uses this reference manager
+	 * @param filter the new filter that is being added
+	 * @return the new reference
 	 */
 	public ISystemFilterReference getSystemFilterReference(ISubSystem subSystem, ISystemFilter filter) {
 		// step 1: find the reference to the filter pool that contains this filter
@@ -639,7 +647,9 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 
 	/**
 	 * Concatenate all filter references from all filter pools we reference, into one
-	 * big list.
+	 * big list. Used when the UI is not showing pools.
+	 * @param subSystem the subsystem for which this manager is providing filter pool reference management
+	 * @return an array of references for this subsystem
 	 */
 	public ISystemFilterReference[] getSystemFilterReferences(ISubSystem subSystem) {
 		ISystemFilterPoolReference[] poolRefs = getSystemFilterPoolReferences();
@@ -657,8 +667,11 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 
 	/**
 	 * Given a filter reference, return its position within this reference manager
-	 *  when you think of all filter references from all filter pool references as 
+	 * when you think of all filter references from all filter pool references as 
-	 *  being concatenated
+	 * being concatenated.
+	 * Used when the UI is not showing pools.
+	 * @param filterRef the reference to locate
+	 * @return the position fo this reference or -1 if not found.
 	 */
 	public int getSystemFilterReferencePosition(ISystemFilterReference filterRef) {
 		ISystemFilterPoolReference[] poolRefs = getSystemFilterPoolReferences();
@@ -678,8 +691,12 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 
 	/**
 	 * Given a filter, return its position within this reference manager
-	 *  when you think of all filter references from all filter pool references as 
+	 * when you think of all filter references from all filter pool references as 
-	 *  being concatenated
+	 * being concatenated.
+	 * Used when the UI is not showing pools.
+	 * @param subSystem the subsystem in which to located the filter
+	 * @param filter the filter to locate
+	 * @return the position of the filter within this manager.
 	 */
 	public int getSystemFilterReferencePosition(ISubSystem subSystem, ISystemFilter filter) {
 		ISystemFilterPoolReference[] poolRefs = getSystemFilterPoolReferences();
@@ -704,25 +721,31 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 		try {
 			save();
 		} catch (Exception exc) {
+			// TODO log exception
 		}
 	}
 
 	/**
 	 * Save all the filter pools to disk.     
-	 * Only called if the save policy is not none.
+	 * Only called if the save policy is not "none".
+	 * No longer used.
+	 * @throws Exception
 	 */
 	public void save() throws Exception {
-		//System.out.println("Saving filter pool " + this.getName() + "?"); // DWD - debugging
 		switch (savePolicy) {
-		// ONE FILE PER FILTER POOL REFERENCE MANAGER
+			// ONE FILE PER FILTER POOL REFERENCE MANAGER
-		case ISystemFilterSavePolicies.SAVE_POLICY_ONE_FILE_PER_MANAGER:
+			case ISystemFilterSavePolicies.SAVE_POLICY_ONE_FILE_PER_MANAGER:
-			saveToOneFile();
+				saveToOneFile();
-			break;
+				break;
 		}
 	}
 
 	/**
 	 * Save this reference manager to disk.
+	 * Used only if using the reference manager to save a single file to disk.
+	 * No longer used.
+	 * @return true if the save succeeded
+	 * @throws Exception
 	 */
 	protected boolean saveToOneFile() throws Exception {
 		/* FIXME
@@ -763,13 +786,14 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 
 	/**
 	 * Restore the filter pools from disk.
-	 * After restoration, you must call resolveReferencesAfterRestore!
+	 * After restoring, you must call resolveReferencesAfterRestore.
+	 * No longer used.
 	 * @param caller The object that is calling this, which must implement SystemFilterPoolReferenceManagerProvider
 	 * @param mgrFolder folder containing filter pool references file.
 	 * @param name the name of the manager to restore. File name is derived from it when saving to one file.
 	 * @param namingPolicy to get file name prefix, via getFilterPoolReferenceManagerFileNamePrefix(). Pass null to use default.
-	 * @return the restored manager, or null if it does not exist. If anything else went
+	 * @return the restored manager, or null if it does not exist.
-	 *  wrong, an exception is thrown.
+	 * @throws Exception if anything else went wrong
 	 */
 	public static ISystemFilterPoolReferenceManager restore(ISystemFilterPoolReferenceManagerProvider caller, IFolder mgrFolder, String name, IRSEFilterNamingPolicy namingPolicy) throws Exception {
 		if (namingPolicy == null) namingPolicy = SystemFilterNamingPolicy.getNamingPolicy();
@@ -781,17 +805,26 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	}
 
 	/**
-	 * Restore the filter pools from disk, assuming default for prefix of name.
+	 * Restore the filter pools from disk, assuming default for a naming policy.
+	 * No longer used.
+	 * @param caller The object that is calling this, which must implement SystemFilterPoolReferenceManagerProvider
+	 * @param mgrFolder folder containing filter pool references file.
+	 * @param name the name of the manager to restore. File name is derived from it when saving to one file.
+	 * @return the restored manager, or null if it does not exist.
+	 * @throws Exception if anything else went wrong
 	 */
 	public static ISystemFilterPoolReferenceManager restore(ISystemFilterPoolReferenceManagerProvider caller, IFolder mgrFolder, String name) throws Exception {
 		return restore(caller, mgrFolder, name, null);
 	}
 
 	/**
-	 * Restore filter pools when all are stored in one file
+	 * Restore filter pools when all are stored in one file.
+	 * No longer used.
 	 * @param mgrFolder The folder containing the file to restore from.
 	 * @param name The name of the manager, from which the file name is derived.
 	 * @param namingPolicy Naming prefix information for persisted data file names.
+	 * @return the restored manager, or null if it does not exist.
+	 * @throws Exception if anything else went wrong
 	 */
 	protected static ISystemFilterPoolReferenceManager restoreFromOneFile(IFolder mgrFolder, String name, IRSEFilterNamingPolicy namingPolicy) throws Exception {
 		ISystemFilterPoolReferenceManager mgr = null;
@@ -841,17 +874,17 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	 * This method is called after restore and for each restored object in the list must:
 	 * <ol>
 	 *   <li>Do what is necessary to find the referenced object, and set the internal reference pointer.
-	 *   <li>Call addReference(this) on that object so it can maintain it's in-memory list
+	 *   <li>Call addReference(this) on that object so it can maintain it's in-memory list of all referencing objects.
-	 *          of all referencing objects.
 	 *   <li>Set the important transient variables 
 	 * </ol>
-	 * @param relatedManagers the filter pool managers that hold filter pools we reference
+	 * @param relatedPoolMgrProvider the filter pool manager provider that created the filter pools we reference
+	 * (usually a subsystem configuration)
 	 * @param provider the host of this reference manager, so you can later call getProvider
 	 * @return A Vector of SystemFilterPoolReferences that were not successfully resolved, or null if all
-	 *   were resolved.
+	 * were resolved.
 	 */
 	public Vector resolveReferencesAfterRestore(ISystemFilterPoolManagerProvider relatedPoolMgrProvider, ISystemFilterPoolReferenceManagerProvider provider) {
-		setSystemFilterPoolManagerProvider(relatedPoolMgrProvider); // sets poolMgrs = relatedManagers
+		setSystemFilterPoolManagerProvider(relatedPoolMgrProvider);
 		setProvider(provider);
 		ISystemFilterPoolManager[] relatedManagers = getSystemFilterPoolManagers();
 		if (relatedManagers != null) {
@@ -867,11 +900,9 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 						//System.out.println("...looking for broken reference for "+mgrName+"."+poolName);
 						refdPool = relatedPoolMgrProvider.getSystemFilterPoolForBrokenReference(this, mgrName, poolName);
 					}
-
 					if (refdPool != null) {
 						poolRefs[idx].setReferenceToFilterPool(refdPool); // calls refdPool.addReference(poolRef)
 					} else {
-
 						badRefs.addElement(poolRefs[idx]);
 					}
 				}
@@ -885,7 +916,6 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 					}
 					invalidateFilterPoolReferencesCache();
 					quietSave();
-					//System.out.println("End of resolveReferencesAfterRestore for provider " + getName());
 					return badRefs;
 				}
 			}
@@ -896,11 +926,11 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	/**
 	 * Utility method to scan across all filter pools in a given named filter pool manager, for a match
 	 * on a given filter pool name.
-	 * <p>
 	 * @param mgrs The list of filter pool managers to scan for the given filter pool.
 	 * @param mgrName The name of the manager to restrict the search to
-	 * @param poolReferenceName The name of the filter pool as stored on disk. It may be qualified somehow
+	 * @param poolName The name of the filter pool as stored on disk. It may be qualified somehow
-	 *  to incorporate the manager name too.
+	 * to incorporate the manager name too.
+	 * @return the filter pool that was found.
 	 */
 	public static ISystemFilterPool getFilterPool(ISystemFilterPoolManager[] mgrs, String mgrName, String poolName) {
 		ISystemFilterPoolManager mgr = getFilterPoolManager(mgrs, mgrName);
@@ -910,9 +940,9 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 
 	/**
 	 * Utility method to scan across all filter pool managers for a match on a give name.
-	 * <p>
 	 * @param mgrs The list of filter pool managers to scan for the given name
 	 * @param mgrName The name of the manager to restrict the search to
+	 * @return the filter pool manager that was found or null if not found.
 	 */
 	public static ISystemFilterPoolManager getFilterPoolManager(ISystemFilterPoolManager[] mgrs, String mgrName) {
 		ISystemFilterPoolManager mgr = null;
@@ -928,56 +958,65 @@ public class SystemFilterPoolReferenceManager extends SystemPersistableReference
 	/**
 	 * If saving all info in one file, this returns the fully qualified name of that file,
 	 * given the unadorned manager name and the prefix (if any) to adorn with.
+	 * No longer used.
+	 * @param mgrFolder The folder in which to save a reference manager.
+	 * @param name The name of the file for a filter pool reference manager.
+	 * @param namingPolicy The naming policy for a filter pool reference manager
+	 * @return The name of the path to which to save the references in a filter pool reference manager.
 	 */
 	protected static String getSaveFilePathAndName(IFolder mgrFolder, String name, IRSEFilterNamingPolicy namingPolicy) {
 		return SystemFilter.addPathTerminator(getFolderPath(mgrFolder)) + getSaveFileName(namingPolicy.getReferenceManagerSaveFileName(name));
 	}
 
 	/**
-	 * Derive and return the unqualified file name used to store this to disk.
+	 * Appends the correct extension to the file name where this manager is saved.
-	 * It is unqualified.
+	 * No longer used.
+	 * @param fileNameNoSuffix the file name <i>sans</i> suffix.
+	 * @return the unqualified file name used to store this to disk.
 	 */
 	protected static String getSaveFileName(String fileNameNoSuffix) {
 		return fileNameNoSuffix + ISystemFilterConstants.SAVEFILE_SUFFIX;
 	}
 
 	/**
-	 * non-static version.
+	 * @return the full path name of the file in which to save this manager.
 	 */
 	protected String getSaveFilePathAndName() {
 		return SystemFilter.addPathTerminator(getFolderPath(mgrFolder)) + getSaveFileName();
 	}
 
 	/**
-	 * non-static version.
+	 * @return the simple name of the file in which to save this manager.
 	 */
 	protected String getSaveFileName() {
 		return getSaveFileName(namingPolicy.getReferenceManagerSaveFileName(getName()));
 	}
 
 	/**
-	 * Return the folder that this manager is contained in.
+	 * @return the folder that this manager is contained in.
 	 */
 	public IFolder getFolder() {
 		return mgrFolder;
 	}
 
 	/**
-	 * Reset the folder that this manager is contained in.
+	 * Set the folder that this manager is contained in.
+	 * @param newFolder the new folder
 	 */
 	public void resetManagerFolder(IFolder newFolder) {
 		mgrFolder = newFolder;
 	}
 
 	/**
-	 * Return the path of the folder
+	 * @return the path of the folder that contains this manager.
 	 */
 	public String getFolderPath() {
 		return getResourceHelpers().getFolderPath(mgrFolder);
 	}
 
 	/**
-	 * Return the path of the given folder
+	 * @param folder the folder to find the path for
+	 * @return the path of the given folder
 	 */
 	public static String getFolderPath(IFolder folder) {
 		return SystemResourceHelpers.getResourceHelpers().getFolderPath(folder);