added javadoc

3 files changed, 53 insertions, 20 deletions

diff --git a/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/IPlanner.java b/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/IPlanner.java
index d7f44bd37..6412b3189 100644
--- a/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/IPlanner.java
+++ b/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/IPlanner.java
@@ -19,9 +19,9 @@ import org.eclipse.equinox.p2.query.IQueryResult;
 /**
  * Planners are responsible for determining what should be done to a given 
  * profile to reshape it as requested. That is, given the current state of a 
- * profile, a description of the desired end state of that profile and metadata 
- * describing the available IUs, a planner produces a plan that lists the
- * provisioning operands that the engine should perform.  
+ * profile, a description of the desired changes to that profile and metadata 
+ * describing the available installable units, a planner produces a concrete plan that lists the
+ * exact steps that the engine should perform.  
  * @since 2.0
  */
 public interface IPlanner {
@@ -31,6 +31,8 @@ public interface IPlanner {
 	public static final String SERVICE_NAME = IPlanner.class.getName();
 
 	/**
+	 * Returns a plan describing the set of changes that must be performed to
+	 * satisfy the given profile change request.
 	 * 
 	 * @param profileChangeRequest the request to be evaluated
 	 * @param context the context in which the request is processed
diff --git a/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/IProfileChangeRequest.java b/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/IProfileChangeRequest.java
index b9f2f67be..9b533a7e2 100644
--- a/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/IProfileChangeRequest.java
+++ b/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/IProfileChangeRequest.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- *  Copyright (c) 2010 Sonatype, Inc.
+ *  Copyright (c) 2010 Sonatype, Inc and others.
  *  All rights reserved. This program and the accompanying materials
  *  are made available under the terms of the Eclipse Public License v1.0
  *  which accompanies this distribution, and is available at
@@ -7,6 +7,7 @@
  * 
  *  Contributors:
  *     Sonatype, Inc. - initial API and implementation
+ *     IBM Corporation - ongoing development
  *******************************************************************************/
 package org.eclipse.equinox.p2.planner;
 
@@ -14,9 +15,14 @@ import java.util.Collection;
 import org.eclipse.equinox.p2.metadata.IInstallableUnit;
 
 /**
- *  A profile change request is a description of a set of changes to be performed on a profile.
- *  A profile change request is then 
+ *  A profile change request is a description of a set of changes that a client
+ *  would like to perform on a profile. The request is provided as input to an
+ *  {@link IPlanner}, which validates which of the requested changes can be
+ *  performed, and what other changes are required in order to make the profile
+ *  state consistent.
+ *  
  * @noimplement This interface is not intended to be implemented by clients.
+ * @noextend This interface is not intended to be extended by clients.
  * @since 2.0
  */
 public interface IProfileChangeRequest {
@@ -29,29 +35,44 @@ public interface IProfileChangeRequest {
 
 	/**
 	 * Causes the installation of all the IUs mentioned
-	 * @param toInstall the installableunits to be added to the profile
+	 * @param toInstall the installable units to be added to the profile
 	 */
 	public abstract void addAll(Collection<IInstallableUnit> toInstall);
 
 	/**
-	 * Causes the removals of all the IUs mentioned
-	 * @param toUninstall the installableunits to be remove from the profile
+	 * Requests the removal of the specified installable unit
+	 * 
+	 * @param toUninstall the installable units to be remove from the profile
 	 */
 	public abstract void remove(IInstallableUnit toUninstall);
 
+	/**
+	 * Requests the removal of all installable units in the provided collection
+	 * @param toUninstall the installable units to be remove from the profile
+	 */
 	public abstract void removeAll(Collection<IInstallableUnit> toUninstall);
 
 	/**
-	 * Associate an inclusion rule with the installable unit. An inclusion rule will dictate whether the 
-	 * @param iu
-	 * @param inclusionRule 
+	 * Associate an inclusion rule with the installable unit. An inclusion rule will dictate how
+	 * the installable unit is treated when its dependencies are not satisfied.
+	 * <p>
+	 * The provided inclusion rule must be one of the values specified in {@link ProfileInclusionRules}.
+	 * </p>
+	 * @param iu the installable unit to set an inclusion rule for
+	 * @param inclusionRule The inclusion rule.
 	 */
 	public abstract void setInstallableUnitInclusionRules(IInstallableUnit iu, String inclusionRule);
 
+	/**
+	 * Removes all inclusion rules associated with the given installable unit
+	 * 
+	 * @param iu the installable unit to remove inclusion rules for
+	 */
 	public abstract void removeInstallableUnitInclusionRules(IInstallableUnit iu);
 
 	/** 
 	 * Set a global property on the profile
+	 * 
 	 * @param key key of the property
 	 * @param value value of the property
 	 */
@@ -59,19 +80,21 @@ public interface IProfileChangeRequest {
 
 	/** 
 	 * Remove a global property on the profile
+	 * 
 	 * @param key key of the property
 	 */
 	public abstract void removeProfileProperty(String key);
 
 	/** 
-	 * Associate a property with a given IU. 
+	 * Associate a property with a given installable unit.
+	 * 
 	 * @param key key of the property
 	 * @param value value of the property
 	 */
 	public abstract void setInstallableUnitProfileProperty(IInstallableUnit iu, String key, String value);
 
 	/** 
-	 * Remove a property with a given IU. 
+	 * Remove a property with a given installable unit.
 	 * @param iu The installable until to remove a property for
 	 * @param key key of the property
 	 */
@@ -79,13 +102,13 @@ public interface IProfileChangeRequest {
 
 	/**
 	 *  Provide the set of installable units that have been requested for addition
-	 * @return a collection of the installable units 
+	 * @return a collection of the installable units to add
 	 */
 	public abstract Collection<IInstallableUnit> getAdditions();
 
 	/**
 	 *  Provide the set of installable units that have been requested for removal
-	 * @return a collection of the installable units
+	 * @return a collection of the installable units to remove
 	 */
 	public abstract Collection<IInstallableUnit> getRemovals();
 
diff --git a/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/ProfileInclusionRules.java b/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/ProfileInclusionRules.java
index 304210767..b69ed3b52 100644
--- a/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/ProfileInclusionRules.java
+++ b/bundles/org.eclipse.equinox.p2.director/src/org/eclipse/equinox/p2/planner/ProfileInclusionRules.java
@@ -24,8 +24,13 @@ public class ProfileInclusionRules {
 	}
 
 	/**
-	 * Provide an inclusion rule to for the installation of the given installable unit
-	 * @param iu the iu to be installed.
+	 * Returns an inclusion rule to strictly install the given installable unit. Strictly
+	 * installed installable units will never be uninstalled in order to satisfy a
+	 * later profile change request. That is, when there is a dependency conflict
+	 * between a strictly installed unit and a non-strict unit, the strictly installed
+	 * installable unit will take precedence.
+	 * 
+	 * @param iu the installable unit to be installed.
 	 * @return an opaque token to be passed to the {@link IProfileChangeRequest#setInstallableUnitInclusionRules(IInstallableUnit, String)}
 	 */
 	public static String createStrictInclusionRule(IInstallableUnit iu) {
@@ -33,8 +38,11 @@ public class ProfileInclusionRules {
 	}
 
 	/**
-	 * Provide an inclusion rule to optionally install the installable unit being specified
-	 * @param iu the iu to be installed.
+	 * Returns an inclusion rule to optionally install the given installable unit. An optionally
+	 * installed installable unit will automatically be removed from the profile if any of
+	 * its dependencies become unsatisfied.
+	 * 
+	 * @param iu the installable unit to be installed.
 	 * @return an opaque token to be passed to the {@link IProfileChangeRequest#setInstallableUnitInclusionRules(IInstallableUnit, String)}
 	 */
 	public static String createOptionalInclusionRule(IInstallableUnit iu) {