Fix API documentation347695_target_ui_api

8 files changed, 256 insertions, 214 deletions

diff --git a/ui/org.eclipse.pde.core/src/org/eclipse/pde/core/target/ITargetLocation.java b/ui/org.eclipse.pde.core/src/org/eclipse/pde/core/target/ITargetLocation.java
index 7ab4053ab0..a0ae5c9a25 100644
--- a/ui/org.eclipse.pde.core/src/org/eclipse/pde/core/target/ITargetLocation.java
+++ b/ui/org.eclipse.pde.core/src/org/eclipse/pde/core/target/ITargetLocation.java
@@ -21,12 +21,24 @@ import org.eclipse.core.runtime.*;
  * to be persisted correctly, clients must provide a factory through the 

  * <code>org.eclipse.pde.core.targetLocations</code> extension point.

  * </p><p>

- * To display an implementation in the PDE UI, clients must supply an adapter factory 

- * that adapts their ITargetLocation implementation to the following: 

+ * To display an implementation in the PDE UI, clients may do the following:

  * </p><p>

- * <code>IWizardNode</code>: Provides a IWizardNode object to supply a wizard for creating new locations of this type

+ * - Implement <code>ITargetLocationWizard</code> and contribute to the <code>org.eclipse.pde.ui.targetLocationProvisioners</code>

+ * extension point.

  * </p><p>

- * <code>ILabelProvider</code>: Provides label text and image for the location implementation in the UI

+ * - Have their target location adapt to <code>org.eclipse.jface.viewers.ILabelProvider</code>

+ * to provide text and icon labels in the target definition wizard and editor.

+ * </p><p>

+ * - Have their target location adapt to <code>org.eclipse.jface.viewers.ITreeContentProvider</code>

+ * to provide children items in the target definition wizard and editor. The children must adapt to

+ * <code>ILabelProvider</code> to get text and icon labels in the tree.

+ * </p><p>

+ * - Have their target location adapt to <code>org.eclipse.pde.ui.target.ITargetLocationEditor</code>

+ * to open an edit wizard when the edit button is pressed on the target definition wizard and editor.

+ * </p><p>

+ * - Have their target location adapt to <code>org.eclipse.pde.ui.target.ITargetLocationUpdater</code>

+ * to run an update job on the location when the update button is pressed on the target definition

+ * wizard and editor.

  * </p>

  * 

  * @since 3.8

diff --git a/ui/org.eclipse.pde.ui/plugin.xml b/ui/org.eclipse.pde.ui/plugin.xml
index 053884b535..5af374c5d3 100644
--- a/ui/org.eclipse.pde.ui/plugin.xml
+++ b/ui/org.eclipse.pde.ui/plugin.xml
@@ -2191,8 +2191,7 @@
             class="org.eclipse.pde.internal.ui.shared.target.InstallableUnitWizard"
             icon="icons/obj16/metadata_repo_obj.gif"
             id="org.eclipse.pde.ui.InstallableUnitProvisioner"
-            name="%targetLocationProvider.IU.name"
-            type="org.eclipse.pde.ui.locationProvider1">
+            name="%targetLocationProvider.IU.name">
          <description>
             %targetLocationProvider.IU.description
          </description>
diff --git a/ui/org.eclipse.pde.ui/schema/targetLocationProvisioners.exsd b/ui/org.eclipse.pde.ui/schema/targetLocationProvisioners.exsd
index 04a5ff619e..bdd3dfb84e 100644
--- a/ui/org.eclipse.pde.ui/schema/targetLocationProvisioners.exsd
+++ b/ui/org.eclipse.pde.ui/schema/targetLocationProvisioners.exsd
@@ -1,182 +1,183 @@
-<?xml version='1.0' encoding='UTF-8'?>

-<!-- Schema file written by PDE -->

-<schema targetNamespace="org.eclipse.pde.ui" xmlns="http://www.w3.org/2001/XMLSchema">

-<annotation>

-      <appInfo>

-         <meta.schema plugin="org.eclipse.pde.ui" id="targetLocationProvisioners" name="Target Location Provisioners"/>

-      </appInfo>

-      <documentation>

-         &lt;p&gt;

-This extension point is used to register new target plug-in location provider. Each plug-in location provider is listed when the user attempts to add plug-ins from the PDE Target Platform&apos;s Preference Page.  The selected location provider is responsible for providing the target location which contain plug-ins the user wants to add to the Target Platform.

-&lt;/p&gt;

-      </documentation>

-   </annotation>

-

-   <element name="extension">

-      <annotation>

-         <appInfo>

-            <meta.element />

-         </appInfo>

-      </annotation>

-      <complexType>

-         <sequence>

-            <element ref="locationProvider" minOccurs="1" maxOccurs="unbounded"/>

-         </sequence>

-         <attribute name="point" type="string" use="required">

-            <annotation>

-               <documentation>

-                  

-               </documentation>

-            </annotation>

-         </attribute>

-         <attribute name="id" type="string">

-            <annotation>

-               <documentation>

-                  

-               </documentation>

-            </annotation>

-         </attribute>

-         <attribute name="name" type="string">

-            <annotation>

-               <documentation>

-                  

-               </documentation>

-               <appInfo>

-                  <meta.attribute translatable="true"/>

-               </appInfo>

-            </annotation>

-         </attribute>

-      </complexType>

-   </element>

-

-   <element name="locationProvider">

-      <annotation>

-         <appInfo>

-            <meta.element labelAttribute="name" icon="icon"/>

-         </appInfo>

-      </annotation>

-      <complexType>

-         <sequence>

-            <element ref="description" minOccurs="0" maxOccurs="1"/>

-         </sequence>

-         <attribute name="id" type="string" use="required">

-            <annotation>

-               <documentation>

-                  a unique identifier of the provisioner

-               </documentation>

-            </annotation>

-         </attribute>

-         <attribute name="name" type="string" use="required">

-            <annotation>

-               <documentation>

-                  human readable name of the provisioner

-               </documentation>

-               <appInfo>

-                  <meta.attribute translatable="true"/>

-               </appInfo>

-            </annotation>

-         </attribute>

-         <attribute name="icon" type="string">

-            <annotation>

-               <documentation>

-                  a relative path of an icon that will be used to visually 

-represent the provisioner.

-               </documentation>

-               <appInfo>

-                  <meta.attribute kind="resource"/>

-               </appInfo>

-            </annotation>

-         </attribute>

-         <attribute name="class" type="string" use="required">

-            <annotation>

-               <documentation>

-                  a class that provides a wizard for the user to add content to the target.  The value of this attribute is the fully qualified name of the Java class that implements &lt;code&gt;org.eclipse.pde.ui.target.ITargetLocationWizard&lt;/code&gt;.

-               </documentation>

-               <appInfo>

-                  <meta.attribute kind="java" basedOn=":org.eclipse.pde.ui.target.ITargetLocationWizard"/>

-               </appInfo>

-            </annotation>

-         </attribute>

-      </complexType>

-   </element>

-

-   <element name="description" type="string">

-      <annotation>

-         <appInfo>

-            <meta.element translatable="true"/>

-         </appInfo>

-         <documentation>

-            human-readable description of the provisioner

-         </documentation>

-      </annotation>

-   </element>

-

-   <annotation>

-      <appInfo>

-         <meta.section type="since"/>

-      </appInfo>

-      <documentation>

-         3.8

-      </documentation>

-   </annotation>

-

-   <annotation>

-      <appInfo>

-         <meta.section type="examples"/>

-      </appInfo>

-      <documentation>

-         &lt;p&gt;

-The following is an example of the extension point:

-&lt;pre&gt;

-   &lt;extension

-         point=&quot;org.eclipse.pde.ui.targetLocationProviders&quot;&gt;

-      &lt;locationProvider

-            icon=&quot;icons/obj16/metadata_repo_obj.gif&quot;

-            id=&quot;org.eclipse.pde.ui.InstallableUnit&quot;

-            name=&quot;%targetLocationProvider.IU.name&quot;

-            type=&quot;InstallableUnit&quot;

-            uifactory=&quot;org.eclipse.pde.internal.ui.shared.target.IUFactory&quot;&gt;

-         &lt;description&gt;

-            %targetLocationProvider.IU.description

-         &lt;/description&gt;

-      &lt;/locationProvider&gt;

-   &lt;/extension&gt;

-&lt;/pre&gt;

-      </documentation>

-   </annotation>

-

-   <annotation>

-      <appInfo>

-         <meta.section type="implementation"/>

-      </appInfo>

-      <documentation>

-         &lt;p&gt;

-PDE supplies an update site location provider to add plug-ins from repositories.

-&lt;/p&gt;

-      </documentation>

-   </annotation>

-

-   <annotation>

-      <appInfo>

-         <meta.section type="copyright"/>

-      </appInfo>

-      <documentation>

-         Copyright (c) 2011 IBM Corporation and others.

-&lt;br&gt;

-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 

-&lt;a href=&quot;http://www.eclipse.org/legal/epl-v10.html&quot;&gt;http://www.eclipse.org/legal/epl-v10.html&lt;/a&gt;.

-      </documentation>

-   </annotation>

-

-   <annotation>

-      <appInfo>

-         <meta.section type="apiInfo"/>

-      </appInfo>

-      <documentation>

-         Each template mut provide an adapter factory to provide labels and contents for the target location. It may optionally implement &lt;code&gt;org.eclipse.pde.ui.ILocationUIFactory&lt;/code&gt; interface if it needs to be seeded with the target definition.

-      </documentation>

-   </annotation>

-

-</schema>

+<?xml version='1.0' encoding='UTF-8'?>
+<!-- Schema file written by PDE -->
+<schema targetNamespace="org.eclipse.pde.ui" xmlns="http://www.w3.org/2001/XMLSchema">
+<annotation>
+      <appInfo>
+         <meta.schema plugin="org.eclipse.pde.ui" id="targetLocationProvisioners" name="Target Location Provisioners"/>
+      </appInfo>
+      <documentation>
+         &lt;p&gt;
+This extension point is used to register a target location provisioner wizard that will create new target locations. Each plug-in provisioner is listed when the user attempts to add plug-ins to a target definition from the Target Platform Preference Page or Target Editor.  The selected provisioner is responsible for providing the target location or locations to add to the target definition.
+&lt;/p&gt;&lt;p&gt;
+Clients can provide their own target location implementations through the &lt;code&gt;org.eclipse.pde.core.targetLocations&lt;/code&gt; extension point.  This extension point allows custom location implementations to be added by the user. Additional UI interaction is handled using the adapter framework (see documentation on &lt;code&gt;org.eclipse.pde.core.target.ITargetDefinition&lt;/code&gt;).
+&lt;/p&gt;
+      </documentation>
+   </annotation>
+
+   <element name="extension">
+      <annotation>
+         <appInfo>
+            <meta.element />
+         </appInfo>
+      </annotation>
+      <complexType>
+         <sequence>
+            <element ref="locationProvider" minOccurs="1" maxOccurs="unbounded"/>
+         </sequence>
+         <attribute name="point" type="string" use="required">
+            <annotation>
+               <documentation>
+                  
+               </documentation>
+            </annotation>
+         </attribute>
+         <attribute name="id" type="string">
+            <annotation>
+               <documentation>
+                  
+               </documentation>
+            </annotation>
+         </attribute>
+         <attribute name="name" type="string">
+            <annotation>
+               <documentation>
+                  
+               </documentation>
+               <appInfo>
+                  <meta.attribute translatable="true"/>
+               </appInfo>
+            </annotation>
+         </attribute>
+      </complexType>
+   </element>
+
+   <element name="locationProvider">
+      <annotation>
+         <appInfo>
+            <meta.element labelAttribute="name" icon="icon"/>
+         </appInfo>
+      </annotation>
+      <complexType>
+         <sequence>
+            <element ref="description" minOccurs="0" maxOccurs="1"/>
+         </sequence>
+         <attribute name="id" type="string" use="required">
+            <annotation>
+               <documentation>
+                  a unique identifier of the provisioner
+               </documentation>
+            </annotation>
+         </attribute>
+         <attribute name="name" type="string" use="required">
+            <annotation>
+               <documentation>
+                  human readable name of the provisioner
+               </documentation>
+               <appInfo>
+                  <meta.attribute translatable="true"/>
+               </appInfo>
+            </annotation>
+         </attribute>
+         <attribute name="icon" type="string">
+            <annotation>
+               <documentation>
+                  a relative path of an icon that will be used to visually 
+represent the provisioner.
+               </documentation>
+               <appInfo>
+                  <meta.attribute kind="resource"/>
+               </appInfo>
+            </annotation>
+         </attribute>
+         <attribute name="class" type="string" use="required">
+            <annotation>
+               <documentation>
+                  a class that provides a wizard for the user to add content to the target.  The value of this attribute is the fully qualified name of the Java class that implements &lt;code&gt;org.eclipse.pde.ui.target.ITargetLocationWizard&lt;/code&gt;.
+               </documentation>
+               <appInfo>
+                  <meta.attribute kind="java" basedOn=":org.eclipse.pde.ui.target.ITargetLocationWizard"/>
+               </appInfo>
+            </annotation>
+         </attribute>
+      </complexType>
+   </element>
+
+   <element name="description" type="string">
+      <annotation>
+         <appInfo>
+            <meta.element translatable="true"/>
+         </appInfo>
+         <documentation>
+            human-readable description of the provisioner
+         </documentation>
+      </annotation>
+   </element>
+
+   <annotation>
+      <appInfo>
+         <meta.section type="since"/>
+      </appInfo>
+      <documentation>
+         3.7 Juno
+      </documentation>
+   </annotation>
+
+   <annotation>
+      <appInfo>
+         <meta.section type="examples"/>
+      </appInfo>
+      <documentation>
+         &lt;p&gt;
+The following is an example of the extension point:
+&lt;pre&gt;
+    &lt;extension
+         point=&quot;org.eclipse.pde.ui.targetLocationProvisioners&quot;&gt;
+      &lt;locationProvider
+            class=&quot;org.eclipse.example.exampleTargetWizard&quot;
+            icon=&quot;icons/obj16/exampleTargetLocation.gif&quot;
+            id=&quot;org.eclipse.example.exampleTargetProvisioner&quot;
+            name=&quot;%targetLocationProvider.example.name&quot;
+         &lt;description&gt;
+            %targetLocationProvider.example.description
+         &lt;/description&gt;
+      &lt;/locationProvider&gt;
+   &lt;/extension&gt;
+&lt;/pre&gt;
+      </documentation>
+   </annotation>
+
+   <annotation>
+      <appInfo>
+         <meta.section type="implementation"/>
+      </appInfo>
+      <documentation>
+         &lt;p&gt;
+PDE supplies an internal location provisioner implementation to add plug-ins from update sites and p2 repositories. See &lt;code&gt;org.eclipse.pde.ui.shared.target.InstallableUnitWizard&lt;/code&gt;.
+&lt;/p&gt;
+      </documentation>
+   </annotation>
+
+   <annotation>
+      <appInfo>
+         <meta.section type="copyright"/>
+      </appInfo>
+      <documentation>
+         Copyright (c) 2011 IBM Corporation and others.
+&lt;br&gt;
+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 
+&lt;a href=&quot;http://www.eclipse.org/legal/epl-v10.html&quot;&gt;http://www.eclipse.org/legal/epl-v10.html&lt;/a&gt;.
+      </documentation>
+   </annotation>
+
+   <annotation>
+      <appInfo>
+         <meta.section type="apiInfo"/>
+      </appInfo>
+      <documentation>
+         The wizard contributed by this extension point must implement &lt;code&gt;org.eclipse.pde.ui.target.ITargetLocationWizard&lt;/code&gt;.
+      </documentation>
+   </annotation>
+
+</schema>
diff --git a/ui/org.eclipse.pde.ui/schema/targetProvisioners.exsd b/ui/org.eclipse.pde.ui/schema/targetProvisioners.exsd
index 110af1f481..4300fd71c4 100644
--- a/ui/org.eclipse.pde.ui/schema/targetProvisioners.exsd
+++ b/ui/org.eclipse.pde.ui/schema/targetProvisioners.exsd
@@ -8,6 +8,8 @@
       <documentation>
          &lt;p&gt;
 This extension point is used to register new target plug-in provisioners. Each plug-in provisioner is listed when the user attempts to add plug-ins from the PDE Target Platform&apos;s Preference Page.  The selected provisioner is responsible for providing the target location which contain plug-ins the user wants to add to the Target Platform.
+&lt;/p&gt;&lt;p&gt;
+This extension point is deprecated.  Please use the &lt;code&gt;org.eclipse.pde.ui.targetLocationProvisioners&lt;/code&gt; extension point instead.
 &lt;/p&gt;
       </documentation>
    </annotation>
@@ -125,7 +127,7 @@ represent the provisioner.
          <meta.section type="since"/>
       </appInfo>
       <documentation>
-         3.8
+         3.3
       </documentation>
    </annotation>
 
@@ -153,16 +155,6 @@ The following is an example of the extension point:
       </documentation>
    </annotation>
 
-   <annotation>
-      <appInfo>
-         <meta.section type="implementation"/>
-      </appInfo>
-      <documentation>
-         &lt;p&gt;
-PDE supplies an update site provisioner to add plug-ins from repositories.
-&lt;/p&gt;
-      </documentation>
-   </annotation>
 
    <annotation>
       <appInfo>
diff --git a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/internal/ui/shared/target/TargetLocationsGroup.java b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/internal/ui/shared/target/TargetLocationsGroup.java
index 8396831f17..a0966ddbb1 100644
--- a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/internal/ui/shared/target/TargetLocationsGroup.java
+++ b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/internal/ui/shared/target/TargetLocationsGroup.java
@@ -317,7 +317,7 @@ public class TargetLocationsGroup {
 						break; //Only open for one selected item
 					}
 				} else if (location instanceof AbstractBundleContainer) {
-					// TODO Custom code for locations that don't use adapaters yet
+					// TODO Custom code for locations that don't use adapters yet
 					Shell parent = fTreeViewer.getTree().getShell();
 					EditBundleContainerWizard wizard = new EditBundleContainerWizard(fTarget, location);
 					WizardDialog dialog = new WizardDialog(parent, wizard);
@@ -560,6 +560,7 @@ public class TargetLocationsGroup {
 							return status.getChildren();
 						}
 					} else {
+						// Always check for provider last to avoid hurting performance
 						ITreeContentProvider provider = (ITreeContentProvider) Platform.getAdapterManager().getAdapter(parentElement, ITreeContentProvider.class);
 						if (provider != null) {
 							return provider.getChildren(parentElement);
diff --git a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationEditor.java b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationEditor.java
index ffe8ce37ab..7c9aaf3b7a 100644
--- a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationEditor.java
+++ b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationEditor.java
@@ -15,19 +15,33 @@ import org.eclipse.pde.core.target.ITargetDefinition;
 import org.eclipse.pde.core.target.ITargetLocation;
 
 /**
- * Target contents that implement or adapt to this interface can be Target contents such as {@link ITargetLocation} implementations The Target Locations and their children can adapt to this interface to convey if they 
- * support removal and updation
+ * Contributed target locations that want to support editing in the target wizard and editor must adapt
+ * their {@link ITargetLocation} to this interface. 
  * 
  * @noextend This interface is not intended to be extended by clients.
  * @since 3.7
  */
 public interface ITargetLocationEditor {
-	// TODO No way to restore selection after
-	// TODO We always perform a normal resolve after, forcing re-resolve ( no way to know result)
-	// TODO No way to consider the current selection
 
+	/**
+	 * Returns whether this target location can be edited by this editor. This method will be 
+	 * called when a selection is made to determine if the edit button should be enabled.
+	 * 
+	 * @param target the target definition being edited
+	 * @param targetLocation the target location to edit
+	 * @return whether this editor can edit the target location
+	 */
 	public boolean canEdit(ITargetDefinition target, ITargetLocation targetLocation);
 
+	/**
+	 * Returns a wizard that will be opened to edit the given target location.  The wizard
+	 * is responsible for modifying the target location and/or target. The target definition
+	 * will be resolved if the wizard completes successfully.
+	 *  
+	 * @param target the target definition being edited
+	 * @param targetLocation the target location to edit
+	 * @return wizard to open for editing the target location
+	 */
 	public IWizard getEditWizard(ITargetDefinition target, ITargetLocation targetLocation);
 
 }
diff --git a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationUpdater.java b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationUpdater.java
index 85342f6fc2..89d9b8562c 100644
--- a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationUpdater.java
+++ b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationUpdater.java
@@ -16,8 +16,8 @@ import org.eclipse.pde.core.target.ITargetDefinition;
 import org.eclipse.pde.core.target.ITargetLocation;
 
 /**
- * Target contents that implement or adapt to this interface can be Target contents such as {@link ITargetLocation} implementations The Target Locations and their children can adapt to this interface to convey if they 
- * support removal and updation
+ * Contributed target locations that want to support updating in the target wizard and editor must adapt
+ * their {@link ITargetLocation} to this interface. 
  * 
  * @noextend This interface is not intended to be extended by clients.
  * @since 3.7
@@ -32,8 +32,29 @@ public interface ITargetLocationUpdater {
 	 */
 	public static final int STATUS_CODE_NO_CHANGE = 101;
 
+	/**
+	 * Returns whether this updater can update the given target location. This method will be called
+	 * when a selection is made to determine if the update button should be enabled.
+	 * 
+	 * @param target the target definition being edited
+	 * @param targetLocation the target location to update
+	 * @return whether this update can update the given target location
+	 */
 	public boolean canUpdate(ITargetDefinition target, ITargetLocation targetLocation);
 
+	/**
+	 * Updates the given target location. If an OK status is returned, the target will be resolved
+	 * unless the status has the code {@link #STATUS_CODE_NO_CHANGE}. If a non-OK status is returned
+	 * the message will be presented to the user.
+	 * <p>
+	 * This method may be called from a non-UI thread.  A progress monitor is provided.
+	 * </p>
+	 * 
+	 * @param target the target definition being edited
+	 * @param targetLocation the target location to update
+	 * @param monitor progress monitor
+	 * @return result of the update, use an OK status with {@link #STATUS_CODE_NO_CHANGE} to indicate everything is up to date
+	 */
 	public IStatus update(ITargetDefinition target, ITargetLocation targetLocation, IProgressMonitor monitor);
 
 }
diff --git a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationWizard.java b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationWizard.java
index 9c4c226604..fabf3961ed 100644
--- a/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationWizard.java
+++ b/ui/org.eclipse.pde.ui/src/org/eclipse/pde/ui/target/ITargetLocationWizard.java
@@ -15,18 +15,20 @@ import org.eclipse.pde.core.target.ITargetDefinition;
 import org.eclipse.pde.core.target.ITargetLocation;
 
 /**
- * This interface represents a wizard which will be used to add plug-ins to 
- * the Target Platform.  Implementors must have a default constructor (zero
+ * This interface represents a wizard which will be used to add target locations
+ * to a target definition.  The wizard will be available from the Add... button
+ * on the locations tab in the target wizard or editor.  Implementors must contribute
+ * their wizards through the <code>org.eclipse.pde.ui.targetLocationProvisioners</code>
+ * extension point.  Implementing classes must have a default constructor (zero
  * arguments) for the class to be created from the extension.
  * 
  * @noextend This interface is not intended to be extended by clients.
  * @since 3.7
  */
-
 public interface ITargetLocationWizard extends IWizard {
 
 	/**
-	 * After this wizard is created, this method will be called, providing this wizard with information
+	 * After the wizard is created this method will be called, providing this wizard with information
 	 * from the target definition the new location(s) will be added to.  It is not recommended that 
 	 * implementors modify the target as UI behaviour is not API (it may change between releases).
 	 * 
@@ -35,10 +37,10 @@ public interface ITargetLocationWizard extends IWizard {
 	public void setTarget(ITargetDefinition target);
 
 	/**
-	 * Returns an array of target locations which contain plug-ins to be added to
-	 * the Target Platform.
+	 * Returns an array of target locations to be added to the target definition. Will be
+	 * called after the wizard is closed.
 	 * 
-	 * @return an array that represent the locations that will provide new plug-ins.
+	 * @return an array of target locations to add to the target definition
 	 */
 	public ITargetLocation[] getLocations();