From 64392290f2b00ff89a3c391777a02b9d39d38671 Mon Sep 17 00:00:00 2001
From: kohsuke <kohsuke@71c3de6d-444a-0410-be80-ed276b4c234a>
Date: Wed, 25 Feb 2009 18:14:39 +0000
Subject: [PATCH] doc improvements

git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@15745 71c3de6d-444a-0410-be80-ed276b4c234a
---
 .../java/hudson/tools/ToolDescriptor.java     |  7 +--
 .../java/hudson/tools/ToolInstallation.java   | 47 +++++++++++++++++--
 .../tools/ToolLocationNodeProperty.java       | 29 ++++++------
 3 files changed, 60 insertions(+), 23 deletions(-)

diff --git a/core/src/main/java/hudson/tools/ToolDescriptor.java b/core/src/main/java/hudson/tools/ToolDescriptor.java
index 2ae35c9fb0..2c6c1fdc14 100644
--- a/core/src/main/java/hudson/tools/ToolDescriptor.java
+++ b/core/src/main/java/hudson/tools/ToolDescriptor.java
@@ -29,11 +29,14 @@ import hudson.model.Describable;
 import hudson.tasks.BuildStep;
 
 /**
+ * {@link Descriptor} for {@link ToolInstallation}.
+ *
  * @author huybrechts
+ * @since 1.286
  */
 public abstract class ToolDescriptor<T extends ToolInstallation> extends Descriptor<ToolInstallation> {
 
-    T[] installations;
+    private T[] installations;
 
     public T[] getInstallations() {                 
         return installations;
@@ -42,6 +45,4 @@ public abstract class ToolDescriptor<T extends ToolInstallation> extends Descrip
     public void setInstallations(T[] installations) {
         this.installations = installations;
     }
-
-    public abstract String getDisplayName();
 }
diff --git a/core/src/main/java/hudson/tools/ToolInstallation.java b/core/src/main/java/hudson/tools/ToolInstallation.java
index 0ce2981e53..12df978370 100644
--- a/core/src/main/java/hudson/tools/ToolInstallation.java
+++ b/core/src/main/java/hudson/tools/ToolInstallation.java
@@ -27,15 +27,38 @@ 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 java.io.Serializable;
 
 /**
+ * Formalization of a tool installed in nodes used for builds
+ * (examples include things like JDKs, Ants, Mavens, and Groovys)
+ *
+ * <p>
+ * You can define such a concept in your plugin entirely on your own, without extending from
+ * this class, but choosing this class as a base class has several benefits:
+ *
+ * <ul>
+ * <li>Hudson allows admins to specify different locations for tools on some slaves.
+ *     For example, JDK on the master might be on /usr/local/java but on a Windows slave
+ *     it could be at c:\Program Files\Java
+ * <li>Hudson can verify the existence of tools and provide warnings and diagnostics for
+ *     admins. (TBD)
+ * <li>Hudson can perform automatic installations for users. (TBD)
+ * </ul>
+ *
+ * <p>
+ * To contribute an extension point, put {@link Extension} on your {@link ToolDescriptor} class.
+ *
  * @author huybrechts
+ * @since 1.286
  */
-public abstract class ToolInstallation implements Serializable, Describable<ToolInstallation> {
+public abstract class ToolInstallation implements Serializable, Describable<ToolInstallation>, ExtensionPoint {
 
     private final String name;
     private final String home;
@@ -45,20 +68,34 @@ public abstract class ToolInstallation implements Serializable, Describable<Tool
         this.home = home;
     }
 
+    /**
+     * Gets the human readable name that identifies this tool among other {@link ToolInstallation}s of the same kind.
+     */
+    public String getName() {
+        return name;
+    }
+
+    /**
+     * Gets the home directory of this tool.
+     * 
+     * The path can be in Unix format as well as in Windows format.
+     * Must be absolute.
+     */
     public String getHome() {
         return home;
     }
 
-    public String getName() {
-        return name;
-    }
-    
     public ToolDescriptor<?> getDescriptor() {
         return (ToolDescriptor) Hudson.getInstance().getDescriptor(getClass());
     }
 
+    /**
+     * Returns all the registered {@link ToolDescriptor}s.
+     */
     public static DescriptorExtensionList<ToolInstallation,ToolDescriptor<?>> all() {
         // use getDescriptorList and not getExtensionList to pick up legacy instances
         return Hudson.getInstance().getDescriptorList(ToolInstallation.class);
     }
+
+    private static final long serialVersionUID = 1L;
 }
diff --git a/core/src/main/java/hudson/tools/ToolLocationNodeProperty.java b/core/src/main/java/hudson/tools/ToolLocationNodeProperty.java
index 111860493c..fe374ed000 100644
--- a/core/src/main/java/hudson/tools/ToolLocationNodeProperty.java
+++ b/core/src/main/java/hudson/tools/ToolLocationNodeProperty.java
@@ -24,25 +24,24 @@
 
 package hudson.tools;
 
-import hudson.model.Node;
-import hudson.model.Hudson;
+import hudson.DescriptorExtensionList;
+import hudson.Extension;
 import hudson.model.Descriptor;
+import hudson.model.Hudson;
+import hudson.model.Node;
 import hudson.slaves.NodeProperty;
 import hudson.slaves.NodePropertyDescriptor;
-import hudson.tasks.Ant;
-import hudson.DescriptorExtensionList;
-import hudson.Extension;
-
-import java.util.*;
-import java.util.concurrent.ConcurrentHashMap;
-
 import org.kohsuke.stapler.DataBoundConstructor;
-import com.thoughtworks.xstream.converters.Converter;
-import com.thoughtworks.xstream.converters.MarshallingContext;
-import com.thoughtworks.xstream.converters.UnmarshallingContext;
-import com.thoughtworks.xstream.io.HierarchicalStreamWriter;
-import com.thoughtworks.xstream.io.HierarchicalStreamReader;
 
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * {@link NodeProperty} that allows users to specify different locations for {@link ToolInstallation}s.
+ *
+ * @since 1.286
+ */
 public class ToolLocationNodeProperty extends NodeProperty<Node> {
 
     private final List<ToolLocation> locations;
@@ -85,7 +84,7 @@ public class ToolLocationNodeProperty extends NodeProperty<Node> {
             return "Tool Locations";
         }
 
-        public synchronized DescriptorExtensionList<ToolInstallation,ToolDescriptor<ToolInstallation>> getToolDescriptors() {
+        public synchronized DescriptorExtensionList<ToolInstallation,ToolDescriptor<?>> getToolDescriptors() {
             return ToolInstallation.all();
         }
 
-- 
GitLab