Make WindowsUtil available for use (#4038)

* Add WindowsUtil into main

* Remove WindowsUtil from test

* Change based on feedback
Co-Authored-By: NMatt Sicker <boards@gmail.com>

* Move and improve comments

* Javadoc fixes

core/src/test/java/hudson/os/WindowsUtil.java → core/src/main/java/jenkins/util/WindowsUtil.java

@@ -34,15 +34,21 @@ import java.util.Arrays;
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 
-import static org.junit.Assert.assertTrue;
-
-// adapted from:
-// https://blogs.msdn.microsoft.com/twistylittlepassagesallalike/2011/04/23/everyone-quotes-command-line-arguments-the-wrong-way/
+/**
+ * Utilities for the Windows Platform.
+ * Adapted from:
+ * https://blogs.msdn.microsoft.com/twistylittlepassagesallalike/2011/04/23/everyone-quotes-command-line-arguments-the-wrong-way/
+ *
+ * @since TODO
+ */
 public class WindowsUtil {
     private static final Pattern NEEDS_QUOTING = Pattern.compile("[\\s\"]");
 
     /**
      * Quotes an argument while escaping special characters interpreted by CreateProcess.
+     *
+     * @param argument argument to be quoted or escaped for windows shells.
+     * @return properly quoted and escaped windows arguemnts.
      */
     public static @Nonnull String quoteArgument(@Nonnull String argument) {
         if (!NEEDS_QUOTING.matcher(argument).find()) return argument;
@@ -80,6 +86,8 @@ public class WindowsUtil {
 
     /**
      * Quotes an argument while escaping special characters suitable for use as an argument to {@code cmd.exe}.
+     * @param argument argument to be quoted or escaped for {@code cmd.exe}.
+     * @return properly quoted and escaped arguments to {@code cmd.exe}.
      */
     public static @Nonnull String quoteArgumentForCmd(@Nonnull String argument) {
         return CMD_METACHARS.matcher(quoteArgument(argument)).replaceAll("^$0");
@@ -87,6 +95,8 @@ public class WindowsUtil {
 
     /**
      * Executes a command and arguments using {@code cmd.exe /C ...}.
+     * @param argv arguments to be quoted or escaped for {@code cmd.exe /C ...}.
+     * @return properly quoted and escaped arguments to {@code cmd.exe /C ...}.
      */
     public static @Nonnull Process execCmd(String... argv) throws IOException {
         String command = Arrays.stream(argv).map(WindowsUtil::quoteArgumentForCmd).collect(Collectors.joining(" "));
@@ -101,10 +111,12 @@ public class WindowsUtil {
      * @return the newly created junction point
      * @throws IOException if the call to mklink exits with a non-zero status code
      * @throws InterruptedException if the call to mklink is interrupted before completing
-     * @throws AssertionError if this method is called on a non-Windows platform
+     * @throws UnsupportedOperationException if this method is called on a non-Windows platform
      */
     public static @Nonnull File createJunction(@Nonnull File junction, @Nonnull File target) throws IOException, InterruptedException {
-        assertTrue(Functions.isWindows());
+        if (!Functions.isWindows()) {
+            throw new UnsupportedOperationException("Can only be called on windows platform");
+        }
         Process mklink = execCmd("mklink", "/J", junction.getAbsolutePath(), target.getAbsolutePath());
         int result = mklink.waitFor();
         if (result != 0) {