more doc improvements

git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@15746 71c3de6d-444a-0410-be80-ed276b4c234a

core/src/main/java/hudson/tools/ToolDescriptor.java

@@ -25,8 +25,6 @@
 package hudson.tools;
 
 import hudson.model.Descriptor;
-import hudson.model.Describable;
-import hudson.tasks.BuildStep;
 
 /**
  * {@link Descriptor} for {@link ToolInstallation}.
@@ -38,10 +36,22 @@ public abstract class ToolDescriptor<T extends ToolInstallation> extends Descrip
 
     private T[] installations;
 
-    public T[] getInstallations() {                 
+    /**
+     * Configured instances of {@link ToolInstallation}s.
+     *
+     * @return
+     *      can be empty but never null. Treat this as a read-only copy, do not mutate.
+     */
+    public T[] getInstallations() {
         return installations;
     }
 
+    /**
+     * Overwrites {@link ToolInstallation}s.
+     *
+     * @return
+     *      can be empty but never null.
+     */
     public void setInstallations(T[] installations) {
         this.installations = installations;
     }

core/src/main/java/hudson/tools/ToolInstallation.java

@@ -24,14 +24,13 @@
 
 package hudson.tools;
 
-import hudson.model.Describable;
-import hudson.model.Descriptor;
-import hudson.model.Hudson;
-import hudson.model.JDK;
 import hudson.DescriptorExtensionList;
-import hudson.ExtensionPoint;
 import hudson.Extension;
-import hudson.tasks.BuildWrapper;
+import hudson.ExtensionPoint;
+import hudson.model.Describable;
+import hudson.model.EnvironmentSpecific;
+import hudson.model.Hudson;
+import hudson.slaves.NodeSpecific;
 
 import java.io.Serializable;
 
@@ -53,6 +52,9 @@ import java.io.Serializable;
  * </ul>
  *
  * <p>
+ * Implementation of this class should consider implementing {@link NodeSpecific} and {@link EnvironmentSpecific}.
+ *
+ * <p>
  * To contribute an extension point, put {@link Extension} on your {@link ToolDescriptor} class.
  *
  * @author huybrechts

test/pom.xml

@@ -132,4 +132,4 @@ THE SOFTWARE.
       <url>http://archiva.openqa.org/repository/releases/</url>
     </repository>
   </repositories>
-</project>
\ No newline at end of file
+</project>