Annotate and document methods of hudson.Launcher (#2920)

* Annotate and document methods of hudson.Launcher

* Fix newly introduced FindBugs issues in hudson.Launcher

* Remove brackets from FilePath#createLauncher() to avoid the merge conflict

core/src/main/java/hudson/EnvVars.java

@@ -211,13 +211,15 @@ public class EnvVars extends TreeMap<String,String> {
         
         private final Comparator<? super String> comparator;
         
+        @Nonnull
         private final EnvVars target;
+        @Nonnull
         private final Map<String,String> overrides;
         
         private Map<String, Set<String>> refereeSetMap;
         private List<String> orderedVariableNames;
         
-        public OverrideOrderCalculator(EnvVars target, Map<String,String> overrides) {
+        public OverrideOrderCalculator(@Nonnull EnvVars target, @Nonnull Map<String,String> overrides) {
             comparator = target.comparator();
             this.target = target;
             this.overrides = overrides;
@@ -324,9 +326,9 @@ public class EnvVars extends TreeMap<String,String> {
     /**
      * Overrides all values in the map by the given map. Expressions in values will be expanded.
      * See {@link #override(String, String)}.
-     * @return this
+     * @return {@code this}
      */
-    public EnvVars overrideExpandingAll(Map<String,String> all) {
+    public EnvVars overrideExpandingAll(@Nonnull Map<String,String> all) {
         for (String key : new OverrideOrderCalculator(this, all).getOrderedVariableNames()) {
             override(key, expand(all.get(key)));
         }

core/src/main/java/hudson/FilePath.java

@@ -235,9 +235,9 @@ public final class FilePath implements Serializable {
      *
      * @param channel
      *      To create a path that represents a remote path, pass in a {@link Channel}
-     *      that's connected to that machine. If null, that means the local file path.
+     *      that's connected to that machine. If {@code null}, that means the local file path.
      */
-    public FilePath(VirtualChannel channel, String remote) {
+    public FilePath(@CheckForNull VirtualChannel channel, @Nonnull String remote) {
         this.channel = channel instanceof LocalChannel ? null : channel;
         this.remote = normalize(remote);
     }
@@ -249,7 +249,7 @@ public final class FilePath implements Serializable {
      * A "local" path means a file path on the computer where the
      * constructor invocation happened.
      */
-    public FilePath(File localPath) {
+    public FilePath(@Nonnull File localPath) {
         this.channel = null;
         this.remote = normalize(localPath.getPath());
     }
@@ -259,12 +259,12 @@ public final class FilePath implements Serializable {
      * @param base starting point for resolution, and defines channel
      * @param rel a path which if relative will be resolved against base
      */
-    public FilePath(FilePath base, String rel) {
+    public FilePath(@Nonnull FilePath base, @Nonnull String rel) {
         this.channel = base.channel;
         this.remote = normalize(resolvePathIfRelative(base, rel));
     }
 
-    private String resolvePathIfRelative(FilePath base, String rel) {
+    private String resolvePathIfRelative(@Nonnull FilePath base, @Nonnull String rel) {
         if(isAbsolute(rel)) return rel;
         if(base.isUnix()) {
             // shouldn't need this replace, but better safe than sorry
@@ -279,7 +279,7 @@ public final class FilePath implements Serializable {
     /**
      * Is the given path name an absolute path?
      */
-    private static boolean isAbsolute(String rel) {
+    private static boolean isAbsolute(@Nonnull String rel) {
         return rel.startsWith("/") || DRIVE_PATTERN.matcher(rel).matches() || UNC_PATTERN.matcher(rel).matches();
     }
 
@@ -291,7 +291,7 @@ public final class FilePath implements Serializable {
      * {@link File#getParent()} etc cannot handle ".." and "." in the path component very well,
      * so remove them.
      */
-    private static String normalize(String path) {
+    private static String normalize(@Nonnull String path) {
         StringBuilder buf = new StringBuilder();
         // Check for prefix designating absolute path
         Matcher m = ABSOLUTE_PREFIX_PATTERN.matcher(path);
@@ -2324,6 +2324,7 @@ public final class FilePath implements Serializable {
     }
 
     private static final class IsUnix extends MasterToSlaveCallable<Boolean,IOException> {
+        @Nonnull
         public Boolean call() throws IOException {
             return File.pathSeparatorChar==':';
         }
@@ -2830,6 +2831,11 @@ public final class FilePath implements Serializable {
                             new NamingThreadFactory(new DaemonThreadFactory(), "FilePath.localPool"))
             ));
 
+    
+    /**
+     * Channel to the current instance.
+     */
+    @Nonnull
     public static final LocalChannel localChannel = new LocalChannel(threadPoolForRemoting);
 
     private @Nonnull SoloFilePathFilter filterNonNull() {

core/src/main/java/hudson/Proc.java

@@ -49,6 +49,7 @@ import java.util.concurrent.Future;
 import java.util.concurrent.TimeUnit;
 import java.util.logging.Level;
 import java.util.logging.Logger;
+import javax.annotation.CheckForNull;
 import org.kohsuke.accmod.Restricted;
 import org.kohsuke.accmod.restrictions.NoExternalUse;
 
@@ -102,10 +103,11 @@ public abstract class Proc {
      * the child process to your {@link OutputStream} of choosing.
      *
      * @return
-     *      null unless {@link ProcStarter#readStdout()} is used to indicate
+     *      {@code null} unless {@link ProcStarter#readStdout()} is used to indicate
      *      that the caller intends to pump the stream by itself.
      * @since 1.399
      */
+    @CheckForNull
     public abstract InputStream getStdout();
 
     /**
@@ -115,10 +117,11 @@ public abstract class Proc {
      * the child process to your {@link OutputStream} of choosing.
      *
      * @return
-     *      null unless {@link ProcStarter#readStderr()} is used to indicate
+     *      {@code null} unless {@link ProcStarter#readStderr()} is used to indicate
      *      that the caller intends to pump the stream by itself.
      * @since 1.399
      */
+    @CheckForNull
     public abstract InputStream getStderr();
 
     /**
@@ -128,10 +131,11 @@ public abstract class Proc {
      * of your choosing to the child process.
      *
      * @return
-     *      null unless {@link ProcStarter#writeStdin()} is used to indicate
+     *      {@code null} unless {@link ProcStarter#writeStdin()} is used to indicate
      *      that the caller intends to pump the stream by itself.
      * @since 1.399
      */
+    @CheckForNull
     public abstract OutputStream getStdin();
 
     private static final ExecutorService executor = Executors.newCachedThreadPool(new ExceptionCatchingThreadFactory(new NamingThreadFactory(new DaemonThreadFactory(), "Proc.executor")));

core/src/main/java/hudson/model/Computer.java

@@ -575,7 +575,7 @@ public /*transient*/ abstract class Computer extends Actionable implements Acces
      *
      * @since 1.624
      * @return
-     *      null if the computer is disconnected and therefore we don't know whether it is Unix or not.
+     *      {@code null} if the computer is disconnected and therefore we don't know whether it is Unix or not.
      */
     public abstract @CheckForNull Boolean isUnix();