Convert parameters from String to File whenever applicable

src/main/java/rife/bld/extension/DokkaOperation.java

@@ -28,6 +28,7 @@ import java.util.*;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.logging.Level;
 import java.util.logging.Logger;
+import java.util.stream.Collectors;
 
 /**
  * Builds documentation (javadoc, HTML, etc.) using Dokka.
@@ -37,6 +38,7 @@ import java.util.logging.Logger;
  */
 @SuppressWarnings("PMD.AvoidThrowingRawExceptionTypes")
 public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
+    public static final String SEMICOLON = ";";
     private final static String GFM_PLUGIN_REGEXP =
             "^.*(dokka-base|analysis-kotlin-descriptors|gfm-plugin|freemarker).*\\.jar$";
     private final static String HTML_PLUGIN_REGEXP =
@@ -49,8 +51,8 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
     private final Map<String, String> globalLinks_ = new ConcurrentHashMap<>();
     private final Collection<String> globalPackageOptions_ = new ArrayList<>();
     private final Collection<String> globalSrcLinks_ = new ArrayList<>();
-    private final Collection<String> includes_ = new ArrayList<>();
-    private final Collection<String> pluginsClasspath_ = new ArrayList<>();
+    private final Collection<File> includes_ = new ArrayList<>();
+    private final Collection<File> pluginsClasspath_ = new ArrayList<>();
     private final Map<String, String> pluginsConfiguration_ = new ConcurrentHashMap<>();
     private boolean delayTemplateSubstitution_;
     private boolean failOnWarning_;
@@ -81,8 +83,8 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
      * @param regex     the regular expression to match
      * @return the list of JARs
      */
-    public static List<String> getJarList(File directory, String regex) {
-        var jars = new ArrayList<String>();
+    public static List<File> getJarList(File directory, String regex) {
+        var jars = new ArrayList<File>();
 
         if (directory.isDirectory()) {
             var files = directory.listFiles();
@@ -90,7 +92,7 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
                 for (var f : files) {
                     if (!f.getName().endsWith("-sources.jar") && (!f.getName().endsWith("-javadoc.jar")) &&
                             f.getName().matches(regex)) {
-                        jars.add(f.getAbsolutePath());
+                        jars.add(f);
                     }
                 }
             }
@@ -146,12 +148,12 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
 
         // -jar dokka-cli
         args.add("-jar");
-        args.add(cli.get(0));
+        args.add(cli.get(0).getAbsolutePath());
 
         // -pluginClasspath
         if (!pluginsClasspath_.isEmpty()) {
             args.add("-pluginsClasspath");
-            args.add(String.join(";", pluginsClasspath_));
+            args.add(pluginsClasspath_.stream().map(File::getAbsolutePath).collect(Collectors.joining(SEMICOLON)));
         }
 
         // -sourceSet
@@ -195,19 +197,19 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
         // -globalPackageOptions
         if (!globalPackageOptions_.isEmpty()) {
             args.add("-globalPackageOptions");
-            args.add(String.join(";", globalPackageOptions_));
+            args.add(String.join(SEMICOLON, globalPackageOptions_));
         }
 
         // -globalSrcLinks
         if (!globalSrcLinks_.isEmpty()) {
             args.add("-globalSrcLinks_");
-            args.add(String.join(";", globalSrcLinks_));
+            args.add(String.join(SEMICOLON, globalSrcLinks_));
         }
 
         // -includes
         if (!includes_.isEmpty()) {
             args.add("-includes");
-            args.add(String.join(";", includes_));
+            args.add(includes_.stream().map(File::getAbsolutePath).collect(Collectors.joining(SEMICOLON)));
         }
 
         // -loggingLevel
@@ -268,7 +270,7 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
      * Configures the operation from a {@link BaseProject}.
      * <p>
      * Sets the {@link #sourceSet sourceSet}, {@link SourceSet#jdkVersion jdkVersion}, {@link #moduleName moduleName}
-     * and {@link SourceSet#classpath(String...) classpath} from the project.
+     * and {@link SourceSet#classpath(File...) classpath} from the project.
      *
      * @param project the project to configure the operation from
      */
@@ -276,7 +278,7 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
     public DokkaOperation fromProject(BaseProject project) {
         project_ = project;
         sourceSet_ = new SourceSet()
-                .src(new File(project.srcMainDirectory(), "kotlin").getAbsolutePath())
+                .src(new File(project.srcMainDirectory(), "kotlin"))
                 .classpath(project.compileClasspathJars())
                 .classpath(project.providedClasspathJars());
         if (project.javaRelease() != null) {
@@ -302,6 +304,15 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
         return this;
     }
 
+    /**
+     * Retrieves the global external documentation links.
+     *
+     * @return the documentation links
+     */
+    public Map<String, String> globalLinks() {
+        return globalLinks_;
+    }
+
     /**
      * Set the global external documentation links.
      *
@@ -348,6 +359,15 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
         return this;
     }
 
+    /**
+     * Retrieves the global list of package configurations.
+     *
+     * @return the package configurations
+     */
+    public Collection<String> globalPackageOptions() {
+        return globalPackageOptions_;
+    }
+
     /**
      * Sets the global list of package configurations.
      * <p>
@@ -381,6 +401,15 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
         return this;
     }
 
+    /**
+     * Retrieves the global source links
+     *
+     * @return the source links
+     */
+    public Collection<String> globalSrcLink() {
+        return globalSrcLinks_;
+    }
+
     /**
      * Sets the global mapping between a source directory and a Web service for browsing the code.
      *
@@ -402,11 +431,37 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
      * @param files one or more files
      * @return this operation instance
      */
-    public DokkaOperation includes(String... files) {
+    public DokkaOperation includes(File... files) {
         Collections.addAll(includes_, files);
         return this;
     }
 
+    /**
+     * Sets the Markdown files that contain module and package documentation.
+     * <p>
+     * The contents of specified files are parsed and embedded into documentation as module and package descriptions.
+     * <p>
+     * This can be configured on per-package basis.
+     *
+     * @param files one or more files
+     * @return this operation instance
+     */
+    public DokkaOperation includes(String... files) {
+        Collections.addAll(includes_, Arrays.stream(files)
+                .map(File::new)
+                .toArray(File[]::new));
+        return this;
+    }
+
+    /**
+     * Retrieves the markdown files that contain the module and package documentation.
+     *
+     * @return the markdown files
+     */
+    public Collection<File> includes() {
+        return includes_;
+    }
+
     /**
      * Sets the Markdown files that contain module and package documentation.
      * <p>
@@ -417,7 +472,7 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
      * @param files the list of files
      * @return this operation instance
      */
-    public DokkaOperation includes(Collection<String> files) {
+    public DokkaOperation includes(Collection<File> files) {
         includes_.addAll(files);
         return this;
     }
@@ -583,6 +638,26 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
         return this;
     }
 
+    /**
+     * Retrieves the plugin configurations.
+     *
+     * @return the plugin configurations.
+     */
+    public Map<String, String> pluginConfigurations() {
+        return pluginsConfiguration_;
+    }
+
+    /**
+     * Sets the list of jars with Dokka plugins and their dependencies.
+     *
+     * @param jars one or more jars
+     * @return this operation instance
+     */
+    public DokkaOperation pluginsClasspath(File... jars) {
+        Collections.addAll(pluginsClasspath_, jars);
+        return this;
+    }
+
     /**
      * Sets the list of jars with Dokka plugins and their dependencies.
      *
@@ -590,34 +665,32 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
      * @return this operation instance
      */
     public DokkaOperation pluginsClasspath(String... jars) {
-        Collections.addAll(pluginsClasspath_, jars);
+        Collections.addAll(pluginsClasspath_, Arrays.stream(jars)
+                .map(File::new)
+                .toArray(File[]::new));
         return this;
     }
 
+    /**
+     * Retrieves the plugins classpath.
+     *
+     * @return the classpath
+     */
+    public Collection<File> pluginsClasspath() {
+        return pluginsClasspath_;
+    }
+
     /**
      * Sets the list of jars with Dokka plugins and their dependencies.
      *
      * @param jars the list of jars
      * @return this operation instance
      */
-    public DokkaOperation pluginsClasspath(Collection<String> jars) {
+    public DokkaOperation pluginsClasspath(Collection<File> jars) {
         pluginsClasspath_.addAll(jars);
         return this;
     }
 
-    /**
-     * Clears the list of Dokka plugins.
-     *
-     * @param clear set to clear the list
-     * @return this operation instance
-     */
-    public DokkaOperation pluginsClasspath(boolean clear) {
-        if (clear) {
-            pluginsClasspath_.clear();
-        }
-        return this;
-    }
-
     /**
      * Sets the configurations for a source set.
      * <p>

src/main/java/rife/bld/extension/dokka/SourceSet.java

@@ -21,6 +21,7 @@ import rife.bld.extension.DokkaOperation;
 import java.io.File;
 import java.util.*;
 import java.util.concurrent.ConcurrentHashMap;
+import java.util.stream.Collectors;
 
 /**
  * Configuration for a Dokka source set.
@@ -29,17 +30,16 @@ import java.util.concurrent.ConcurrentHashMap;
  * @since 1.0
  */
 public class SourceSet {
-    private static final String SEMICOLON = ";";
-    private final Collection<String> classpath_ = new ArrayList<>();
+    private final Collection<File> classpath_ = new ArrayList<>();
     private final Map<String, String> dependentSourceSets_ = new ConcurrentHashMap<>();
     private final Collection<DocumentedVisibility> documentedVisibilities_ = new ArrayList<>();
     private final Map<String, String> externalDocumentationLinks_ = new ConcurrentHashMap<>();
-    private final Collection<String> includes_ = new ArrayList<>();
+    private final Collection<File> includes_ = new ArrayList<>();
     private final Collection<String> perPackageOptions_ = new ArrayList<>();
-    private final Collection<String> samples_ = new ArrayList<>();
+    private final Collection<File> samples_ = new ArrayList<>();
     private final Map<String, String> srcLinks_ = new ConcurrentHashMap<>();
-    private final Collection<String> src_ = new ArrayList<>();
-    private final Collection<String> suppressedFiles_ = new ArrayList<>();
+    private final Collection<File> src_ = new ArrayList<>();
+    private final Collection<File> suppressedFiles_ = new ArrayList<>();
     private AnalysisPlatform analysisPlatform_;
     private String apiVersion_;
     private String displayName_;
@@ -110,7 +110,7 @@ public class SourceSet {
         // -classpath
         if (!classpath_.isEmpty()) {
             args.add("-classpath");
-            args.add(String.join(SEMICOLON, classpath_));
+            args.add(classpath_.stream().map(File::getAbsolutePath).collect(Collectors.joining(DokkaOperation.SEMICOLON)));
         }
 
         // -dependentSourceSets
@@ -118,7 +118,7 @@ public class SourceSet {
             args.add("-dependentSourceSets");
             var deps = new ArrayList<String>();
             dependentSourceSets_.forEach((k, v) -> deps.add(String.format("%s/%s", k, v)));
-            args.add(String.join(SEMICOLON, deps));
+            args.add(String.join(DokkaOperation.SEMICOLON, deps));
         }
 
         // -displayName
@@ -132,7 +132,7 @@ public class SourceSet {
             args.add("-documentedVisibilities");
             var vis = new ArrayList<String>();
             documentedVisibilities_.forEach(d -> vis.add(d.name().toLowerCase()));
-            args.add(String.join(SEMICOLON, vis));
+            args.add(String.join(DokkaOperation.SEMICOLON, vis));
         }
 
         // -externalDocumentationLinks
@@ -152,7 +152,7 @@ public class SourceSet {
         // -includes
         if (!includes_.isEmpty()) {
             args.add("-includes");
-            args.add(String.join(SEMICOLON, includes_));
+            args.add(includes_.stream().map(File::getAbsolutePath).collect(Collectors.joining(DokkaOperation.SEMICOLON)));
         }
 
         // -languageVersion
@@ -188,13 +188,13 @@ public class SourceSet {
         // -perPackageOptions
         if (!perPackageOptions_.isEmpty()) {
             args.add("-perPackageOptions");
-            args.add(String.join(SEMICOLON, perPackageOptions_));
+            args.add(String.join(DokkaOperation.SEMICOLON, perPackageOptions_));
         }
 
         // -samples
         if (!samples_.isEmpty()) {
             args.add("-samples");
-            args.add(String.join(SEMICOLON, samples_));
+            args.add(samples_.stream().map(File::getAbsolutePath).collect(Collectors.joining(DokkaOperation.SEMICOLON)));
         }
 
         // -skipDeprecated
@@ -206,7 +206,7 @@ public class SourceSet {
         // -src
         if (!src_.isEmpty()) {
             args.add("-src");
-            args.add(String.join(SEMICOLON, src_));
+            args.add(src_.stream().map(File::getAbsolutePath).collect(Collectors.joining(DokkaOperation.SEMICOLON)));
         }
 
         // -srcLink
@@ -214,7 +214,7 @@ public class SourceSet {
             args.add("-srcLink");
             var links = new ArrayList<String>();
             srcLinks_.forEach((k, v) -> links.add(String.format("%s=%s", k, v)));
-            args.add(String.join(SEMICOLON, links));
+            args.add(String.join(DokkaOperation.SEMICOLON, links));
         }
 
         // -sourceSetName
@@ -226,7 +226,7 @@ public class SourceSet {
         // -suppressedFiles
         if (!suppressedFiles_.isEmpty()) {
             args.add("-suppressedFiles");
-            args.add(String.join(SEMICOLON, suppressedFiles_));
+            args.add(suppressedFiles_.stream().map(File::getAbsolutePath).collect(Collectors.joining(DokkaOperation.SEMICOLON)));
         }
 
         return args;
@@ -242,7 +242,7 @@ public class SourceSet {
      * @param files one or more file
      * @return this operation instance
      */
-    public SourceSet classpath(String... files) {
+    public SourceSet classpath(File... files) {
         Collections.addAll(classpath_, files);
         return this;
     }
@@ -254,11 +254,13 @@ public class SourceSet {
      * <p>
      * This option accepts both {@code .jar} and {@code .klib} files.
      *
-     * @param files the list of files
+     * @param files one or more file
      * @return this operation instance
      */
-    public SourceSet classpath(Collection<String> files) {
-        classpath_.addAll(files);
+    public SourceSet classpath(String... files) {
+        Collections.addAll(classpath_, Arrays.stream(files)
+                .map(File::new)
+                .toArray(File[]::new));
         return this;
     }
 
@@ -272,11 +274,20 @@ public class SourceSet {
      * @param files the list of files
      * @return this operation instance
      */
-    public SourceSet classpath(List<File> files) {
-        files.forEach(it -> classpath_.add(it.getAbsolutePath()));
+    public SourceSet classpath(Collection<File> files) {
+        classpath_.addAll(files);
         return this;
     }
 
+    /**
+     * Retrieves the classpath for analysis and interactive samples.
+     *
+     * @return the classpath
+     */
+    public Collection<File> classpath() {
+        return classpath_;
+    }
+
     /**
      * Sets the names of dependent source sets.
      *
@@ -289,6 +300,15 @@ public class SourceSet {
         return this;
     }
 
+    /**
+     * Retrieves the names of dependent source sets.
+     *
+     * @return the names
+     */
+    public Map<String, String> dependentSourceSets() {
+        return dependentSourceSets_;
+    }
+
     /**
      * Sets the names of dependent source sets.
      *
@@ -333,6 +353,15 @@ public class SourceSet {
         return this;
     }
 
+    /**
+     * Retrieves the visibilities to be documented.
+     *
+     * @return the documented visibilities
+     */
+    public Collection<DocumentedVisibility> documentedVisibilities() {
+        return documentedVisibilities_;
+    }
+
     /**
      * Sets the external documentation links.
      * <p>
@@ -347,6 +376,15 @@ public class SourceSet {
         return this;
     }
 
+    /**
+     * Retrieves the external documentation links.
+     *
+     * @return the documentation links.
+     */
+    public Map<String, String> externalDocumentationLinks() {
+        return externalDocumentationLinks_;
+    }
+
     /**
      * Sets the external documentation links.
      * <p>
@@ -372,11 +410,38 @@ public class SourceSet {
      * @param files one or more files
      * @return this operation instance
      */
-    public SourceSet includes(String... files) {
+    public SourceSet includes(File... files) {
         Collections.addAll(includes_, files);
         return this;
     }
 
+    /**
+     * Sets the Markdown files that contain module and package documentation.
+     * <p>
+     * A list of Markdown files that contain module and package documentation.
+     * <p>
+     * The contents of the specified files are parsed and embedded into documentation as module and package
+     * descriptions.
+     *
+     * @param files one or more files
+     * @return this operation instance
+     */
+    public SourceSet includes(String... files) {
+        Collections.addAll(includes_, Arrays.stream(files)
+                .map(File::new)
+                .toArray(File[]::new));
+        return this;
+    }
+
+    /**
+     * Retrieves the Markdown files that contain module and package documentation.
+     *
+     * @return the markdown files
+     */
+    public Collection<File> includes() {
+        return includes_;
+    }
+
     /**
      * Sets the Markdown files that contain module and package documentation.
      * <p>
@@ -388,7 +453,7 @@ public class SourceSet {
      * @param files the list of files
      * @return this operation instance
      */
-    public SourceSet includes(Collection<String> files) {
+    public SourceSet includes(Collection<File> files) {
         includes_.addAll(files);
         return this;
     }
@@ -517,6 +582,15 @@ public class SourceSet {
         return this;
     }
 
+    /**
+     * Retrieves the list of package source set configuration.
+     *
+     * @return the package source set configuration
+     */
+    public Collection<String> perPackageOptions() {
+        return perPackageOptions_;
+    }
+
     /**
      * Set the list of package source set configuration.
      * <p>
@@ -568,11 +642,34 @@ public class SourceSet {
      * @param samples the list of samples
      * @return this operation instance
      */
-    public SourceSet samples(Collection<String> samples) {
+    public SourceSet samples(Collection<File> samples) {
         samples_.addAll(samples);
         return this;
     }
 
+    /**
+     * Retrieves the list of directories or files that contain sample functions.
+     *
+     * @return the directories or files
+     */
+    public Collection<File> samples() {
+        return samples_;
+    }
+
+    /**
+     * Set the list of directories or files that contain sample functions.
+     * <p>
+     * A list of directories or files that contain sample functions which are referenced via the {@code @sample} KDoc
+     * tag.
+     *
+     * @param samples nne or more samples
+     * @return this operation instance
+     */
+    public SourceSet samples(File... samples) {
+        Collections.addAll(samples_, samples);
+        return this;
+    }
+
     /**
      * Set the list of directories or files that contain sample functions.
      * <p>
@@ -583,7 +680,9 @@ public class SourceSet {
      * @return this operation instance
      */
     public SourceSet samples(String... samples) {
-        Collections.addAll(samples_, samples);
+        Collections.addAll(samples_, Arrays.stream(samples)
+                .map(File::new)
+                .toArray(File[]::new));
         return this;
     }
 
@@ -622,7 +721,7 @@ public class SourceSet {
      * @param src the list of source code roots
      * @return this operation instance
      */
-    public SourceSet src(Collection<String> src) {
+    public SourceSet src(Collection<File> src) {
         src_.addAll(src);
         return this;
     }
@@ -636,11 +735,36 @@ public class SourceSet {
      * @param src pne ore moe source code roots
      * @return this operation instance
      */
-    public SourceSet src(String... src) {
+    public SourceSet src(File... src) {
         Collections.addAll(src_, src);
         return this;
     }
 
+    /**
+     * Sets the source code roots to be analyzed and documented.
+     * <p>
+     * The source code roots to be analyzed and documented. Acceptable inputs are directories and individual
+     * {@code .kt} / {@code .java} files.
+     *
+     * @param src pne ore moe source code roots
+     * @return this operation instance
+     */
+    public SourceSet src(String... src) {
+        Collections.addAll(src_, Arrays.stream(src)
+                .map(File::new)
+                .toArray(File[]::new));
+        return this;
+    }
+
+    /**
+     * Retrieves the source code roots to be analyzed and documented.
+     *
+     * @return the source code roots
+     */
+    public Collection<File> src() {
+        return src_;
+    }
+
     /**
      * Sets the mapping between a source directory and a Web service for browsing the code.
      *
@@ -654,6 +778,28 @@ public class SourceSet {
         return this;
     }
 
+    /**
+     * Sets the mapping between a source directory and a Web service for browsing the code.
+     *
+     * @param srcPath    the source path
+     * @param remotePath the remote path
+     * @param lineSuffix the line suffix
+     * @return this operation instance
+     */
+    public SourceSet srcLink(File srcPath, String remotePath, String lineSuffix) {
+        srcLinks_.put(srcPath.getAbsolutePath(), remotePath + lineSuffix);
+        return this;
+    }
+
+    /**
+     * Retrieves the mapping between a source directory and a Web service for browsing the code.
+     *
+     * @return the source links
+     */
+    public Map<String, String> srcLinks() {
+        return srcLinks_;
+    }
+
     /**
      * Sets the paths to files to be suppressed.
      * <p>
@@ -662,11 +808,21 @@ public class SourceSet {
      * @param suppressedFiles the list of suppressed files
      * @return this operation instance
      */
-    public SourceSet suppressedFiles(Collection<String> suppressedFiles) {
+    public SourceSet suppressedFiles(Collection<File> suppressedFiles) {
         suppressedFiles_.addAll(suppressedFiles);
         return this;
     }
 
+
+    /**
+     * Retrieves the paths to files to be suppressed.
+     *
+     * @return the paths
+     */
+    public Collection<File> suppressedFiles() {
+        return suppressedFiles_;
+    }
+
     /**
      * Sets the paths to files to be suppressed.
      * <p>
@@ -676,6 +832,21 @@ public class SourceSet {
      * @return this operation instance
      */
     public SourceSet suppressedFiles(String... suppressedFiles) {
+        Collections.addAll(suppressedFiles_, Arrays.stream(suppressedFiles)
+                .map(File::new)
+                .toArray(File[]::new));
+        return this;
+    }
+
+    /**
+     * Sets the paths to files to be suppressed.
+     * <p>
+     * The files to be suppressed when generating documentation.
+     *
+     * @param suppressedFiles one or moe suppressed files
+     * @return this operation instance
+     */
+    public SourceSet suppressedFiles(File... suppressedFiles) {
         suppressedFiles_.addAll(Arrays.asList(suppressedFiles));
         return this;
     }