From 79254d96425d68a2ef58df6b28c89eea6ee26e4c Mon Sep 17 00:00:00 2001
From: "Erik C. Thauvin" <erik@thauvin.net>
Date: Sun, 5 Nov 2023 06:40:58 -0800
Subject: [PATCH] Added more Dokka options

---
 README.md                                     |  26 ++-
 examples/.idea/misc.xml                       |   4 +
 .../bld/java/com/example/ExampleBuild.java    |   2 +
 .../src/main/kotlin/com/example/Example.kt    |  15 ++
 .../bld/extension/dokka/DokkaOperation.java   | 119 +++++++++++--
 .../rife/bld/extension/dokka/SourceSet.java   | 168 +++++++++++++++---
 6 files changed, 298 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index 8a8b01c..239a949 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,8 @@
 
 To install, please refer to the [extensions documentation](https://github.com/rife2/bld/wiki/Extensions).
 
-To compile the Kotlin source code from the current project located in `src/main/kotlin` and `src/test/kotlin`:
+## Compile Kotlin Source Code
+To compile the source code located in `src/main/kotlin` and `src/test/kotlin` from the current project:
 
 ```java
 @BuildCommand(summary = "Compile the Kotlin project")
@@ -27,4 +28,25 @@ public void compile() throws IOException {
 ```
 - [View Examples Project](https://github.com/rife2/bld-kotlin/tree/main/examples/)
 
-Please check the [Compile Operation documentation](https://rife2.github.io/bld-kotlin/rife/bld/extension/CompileKotlinOperation.html#method-summary) for all available configuration options.
+Please check the [Compile Operation documentation](https://rife2.github.io/bld-kotlin/rife/bld/extension/CompileKotlinOperation.html#method-summary)
+for all available configuration options.
+
+## Generate Javadoc
+
+To generate the Javadoc using [Dokka](https://github.com/Kotlin/dokka):
+
+```java
+@BuildCommand(summary = "Generates Javadoc for the project")
+public void javadoc() throws ExitStatusException, IOException, InterruptedException {
+    new DokkaOperation()
+            .fromProject(this)
+            .execute();
+}
+```
+```
+./bld javadoc
+```
+- [View Examples Project](https://github.com/rife2/bld-kotlin/tree/main/examples/)
+
+Please check the [Dokka Operation documentation](https://rife2.github.io/bld-kotlin/rife/bld/extension/dokka/DokkaOperation.html)
+for all available configuration options.
diff --git a/examples/.idea/misc.xml b/examples/.idea/misc.xml
index a89d571..ba68603 100644
--- a/examples/.idea/misc.xml
+++ b/examples/.idea/misc.xml
@@ -1,5 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
+  <component name="EntryPointsManager">
+    <pattern value="com.example.ExampleBuild" />
+    <pattern value="com.example.ExampleBuild" method="javadoc" />
+  </component>
   <component name="PDMPlugin">
     <option name="customRuleSets">
       <list>
diff --git a/examples/src/bld/java/com/example/ExampleBuild.java b/examples/src/bld/java/com/example/ExampleBuild.java
index 52cbfbe..6531a3b 100644
--- a/examples/src/bld/java/com/example/ExampleBuild.java
+++ b/examples/src/bld/java/com/example/ExampleBuild.java
@@ -4,6 +4,7 @@ import rife.bld.BaseProject;
 import rife.bld.BuildCommand;
 import rife.bld.extension.CompileKotlinOperation;
 import rife.bld.extension.dokka.DokkaOperation;
+import rife.bld.extension.dokka.LoggingLevel;
 import rife.bld.operations.exceptions.ExitStatusException;
 
 import java.io.IOException;
@@ -57,6 +58,7 @@ public class ExampleBuild extends BaseProject {
     public void javadoc() throws ExitStatusException, IOException, InterruptedException {
         new DokkaOperation()
                 .fromProject(this)
+                .loggingLevel(LoggingLevel.INFO)
                 .execute();
     }
 }
\ No newline at end of file
diff --git a/examples/src/main/kotlin/com/example/Example.kt b/examples/src/main/kotlin/com/example/Example.kt
index 6750d1e..4055391 100644
--- a/examples/src/main/kotlin/com/example/Example.kt
+++ b/examples/src/main/kotlin/com/example/Example.kt
@@ -1,10 +1,25 @@
 package com.example
 
+/**
+ * Example class.
+ */
 class Example {
+    /**
+     * Message property.
+     */
     val message: String
+        /**
+         * Returns the message property.
+         */
         get() = "Hello World!"
 
+    /**
+     * Companion object.
+     */
     companion object {
+        /**
+         * Main function.
+         */
         @JvmStatic
         fun main(args: Array<String>) {
             println(Example().message)
diff --git a/src/main/java/rife/bld/extension/dokka/DokkaOperation.java b/src/main/java/rife/bld/extension/dokka/DokkaOperation.java
index be8145e..5b1455d 100644
--- a/src/main/java/rife/bld/extension/dokka/DokkaOperation.java
+++ b/src/main/java/rife/bld/extension/dokka/DokkaOperation.java
@@ -18,6 +18,7 @@ package rife.bld.extension.dokka;
 
 import rife.bld.BaseProject;
 import rife.bld.operations.AbstractProcessOperation;
+import rife.tools.StringUtils;
 
 import java.io.File;
 import java.util.*;
@@ -36,20 +37,20 @@ 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<File> includes_ = new ArrayList<>();
+    private final Collection<String> includes_ = new ArrayList<>();
     private final Map<String, String> pluginConfiguration_ = new ConcurrentHashMap<>();
     private final Collection<String> pluginsClasspath_ = new ArrayList<>();
-    private Boolean delayTemplateSubstitution_;
-    private Boolean failOnWarning_;
+    private boolean delayTemplateSubstitution_;
+    private boolean failOnWarning_;
     private LoggingLevel loggingLevel_;
     private String moduleName_;
     private String moduleVersion_;
-    private Boolean noSuppressObviousFunctions_;
-    private Boolean offlineMode_;
+    private boolean noSuppressObviousFunctions_;
+    private boolean offlineMode_;
     private File outputDir_;
     private BaseProject project_;
     private SourceSet sourceSet_;
-    private Boolean suppressInheritedMembers_;
+    private boolean suppressInheritedMembers_;
 
     /**
      * Sets the delay substitution of some elements. Used in incremental builds of multimodule projects.
@@ -104,12 +105,101 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
             args.add(String.join(" ", sourceSet_.args()));
         }
 
-        // -outputdir
-        if (outputDir_ == null) {
-            outputDir_ = new File("./dokka");
+        // -outputDir
+        if (outputDir_ != null) {
+            if (!outputDir_.exists()) {
+                if (!outputDir_.mkdirs()) {
+                    throw new RuntimeException("Could not create: " + outputDir_.getAbsolutePath());
+                }
+            }
+
+            args.add("-outputDir");
+            args.add(outputDir_.getAbsolutePath());
+        }
+
+        // -delayTemplateSubstitution
+        if (delayTemplateSubstitution_) {
+            args.add("-delayTemplateSubstitution");
+            args.add(String.valueOf(delayTemplateSubstitution_));
+        }
+
+        // -failOnWarning
+        if (failOnWarning_) {
+            args.add("-failOnWarning");
+            args.add(String.valueOf(failOnWarning_));
+        }
+
+        // -globalLinks_
+        if (!globalLinks_.isEmpty()) {
+            args.add("-globalLinks");
+            var links = new ArrayList<String>();
+            globalLinks_.forEach((k, v) ->
+                    links.add(String.format("{%s}^{%s}", k, v)));
+            args.add(String.join("^^", links));
+        }
+
+        // -globalPackageOptions
+        if (!globalPackageOptions_.isEmpty()) {
+            args.add("-globalPackageOptions");
+            args.add(String.join(";", globalPackageOptions_));
+        }
+
+        // -globalSrcLinks
+        if (!globalSrcLinks_.isEmpty()) {
+            args.add("-globalSrcLinks_");
+            args.add(String.join(";", globalSrcLinks_));
+        }
+
+        // -includes
+        if (!includes_.isEmpty()) {
+            args.add("-includes");
+            args.add(String.join(";", includes_));
+        }
+
+        // -loggingLevel
+        if (loggingLevel_ != null) {
+            args.add("-loggingLevel");
+            args.add(loggingLevel_.name().toLowerCase());
+        }
+
+        // -moduleName
+        if (moduleName_ != null) {
+            args.add("-moduleName");
+            args.add(moduleName_);
+        }
+
+        // -moduleVersion
+        if (moduleVersion_ != null) {
+            args.add("-moduleVersion");
+            args.add(moduleVersion_);
+        }
+
+        // -noSuppressObviousFunctions
+        if (noSuppressObviousFunctions_) {
+            args.add("-noSuppressObviousFunctions");
+            args.add(String.valueOf(noSuppressObviousFunctions_));
+        }
+
+        // -offlineMode
+        if (offlineMode_) {
+            args.add("-offlineMode");
+            args.add(String.valueOf(offlineMode_));
+        }
+
+        // -pluginConfiguration
+        if (!pluginConfiguration_.isEmpty()) {
+            args.add("-pluginConfiguration");
+            var confs = new ArrayList<String>();
+            pluginConfiguration_.forEach((k, v) ->
+                    confs.add(String.format("{%s}={%s}", StringUtils.encodeJson(k), StringUtils.encodeJson(v))));
+            args.add(String.join("^^", confs));
+        }
+
+        // -suppressInheritedMembers
+        if (suppressInheritedMembers_) {
+            args.add("-suppressInheritedMembers");
+            args.add(String.valueOf(suppressInheritedMembers_));
         }
-        args.add("-outputDir");
-        args.add(outputDir_.getAbsolutePath());
 
         if (LOGGER.isLoggable(Level.FINE)) {
             LOGGER.fine(String.join(" ", args));
@@ -130,8 +220,9 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
                 project.libBldDirectory(),
                 "^.*(dokka-base|analysis-kotlin-descriptors|javadoc-plugin|kotlin-as-java-plugin|korte-jvm).*\\.jar$");
         pluginsClasspath_.addAll(plugins);
-        sourceSet_ = new SourceSet().src(new File(project.srcMainDirectory(), "kotlin"));
+        sourceSet_ = new SourceSet().src(new File(project.srcMainDirectory(), "kotlin").getAbsolutePath());
         outputDir_ = new File(project.buildDirectory(), "javadoc");
+        moduleName_ = project.name();
         return this;
     }
 
@@ -255,7 +346,7 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
      * @param files one or more files
      * @return this operation instance
      */
-    public DokkaOperation includes(File... files) {
+    public DokkaOperation includes(String... files) {
         includes_.addAll(Arrays.asList(files));
         return this;
     }
@@ -266,7 +357,7 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
      * @param files the list of files
      * @return this operation instance
      */
-    public DokkaOperation includss(Collection<File> files) {
+    public DokkaOperation includes(Collection<String> files) {
         includes_.addAll(files);
         return this;
     }
diff --git a/src/main/java/rife/bld/extension/dokka/SourceSet.java b/src/main/java/rife/bld/extension/dokka/SourceSet.java
index ac9177c..89bc443 100644
--- a/src/main/java/rife/bld/extension/dokka/SourceSet.java
+++ b/src/main/java/rife/bld/extension/dokka/SourceSet.java
@@ -16,7 +16,6 @@
 
 package rife.bld.extension.dokka;
 
-import java.io.File;
 import java.util.*;
 import java.util.concurrent.ConcurrentHashMap;
 
@@ -27,25 +26,26 @@ import java.util.concurrent.ConcurrentHashMap;
  * @since 1.0
  */
 public class SourceSet {
-    private final Collection<File> classpath_ = new ArrayList<>();
+    private static final String SEMICOLON = ";";
+    private final Collection<String> 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<File> includes_ = new ArrayList<>();
+    private final Collection<String> includes_ = new ArrayList<>();
     private final Collection<String> perPackageOptions_ = new ArrayList<>();
-    private final Collection<File> samples_ = new ArrayList<>();
+    private final Collection<String> samples_ = new ArrayList<>();
     private final Map<String, String> srcLinks_ = new ConcurrentHashMap<>();
-    private final Collection<File> src_ = new ArrayList<>();
-    private final Collection<File> suppressedFiles_ = new ArrayList<>();
+    private final Collection<String> src_ = new ArrayList<>();
+    private final Collection<String> suppressedFiles_ = new ArrayList<>();
     private AnalysisPlatform analysisPlatform_;
     private String apiVersion_;
     private String displayName_;
     private int jdkVersion_;
     private String languageVersion_;
-    private Boolean noJdkLink_;
+    private boolean noJdkLink_;
     private boolean noSkipEmptyPackages_;
-    private Boolean noStdlibLink_;
-    private Boolean reportUndocumented_;
+    private boolean noStdlibLink_;
+    private boolean reportUndocumented_;
     private boolean skipDeprecated_;
     private String sourceSetName_;
 
@@ -79,10 +79,138 @@ public class SourceSet {
     public List<String> args() {
         var args = new ArrayList<String>();
 
+        // -analysisPlatform
+        if (analysisPlatform_ != null) {
+            args.add("-analysisPlatform");
+            args.add(analysisPlatform_.name().toLowerCase());
+        }
+
+        // -apiVersion
+        if (apiVersion_ != null) {
+            args.add("-apiVersion");
+            args.add(apiVersion_);
+        }
+
+        // -classpath
+        if (!classpath_.isEmpty()) {
+            args.add("-classpath");
+            args.add(String.join(SEMICOLON, classpath_));
+        }
+
+        // -dependentSourceSets
+        if (!dependentSourceSets_.isEmpty()) {
+            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));
+        }
+
+        // -displayName
+        if (displayName_ != null) {
+            args.add("-displayName");
+            args.add(displayName_);
+        }
+
+        // -documentedVisibilities
+        if (!documentedVisibilities_.isEmpty()) {
+            args.add("-documentedVisibilities");
+            var vis = new ArrayList<String>();
+            documentedVisibilities_.forEach(d -> vis.add(d.name().toLowerCase()));
+            args.add(String.join(SEMICOLON, vis));
+        }
+
+        // -externalDocumentationLinks
+        if (!externalDocumentationLinks_.isEmpty()) {
+            args.add("-externalDocumentationLinks");
+            var links = new ArrayList<String>();
+            externalDocumentationLinks_.forEach((k, v) -> links.add(String.format("{%s}^{%s}", k, v)));
+            args.add(String.join("^^", links));
+        }
+
+        // -jdkVersion
+        if (jdkVersion_ > 0) {
+            args.add("-jdkVersion");
+            args.add(String.valueOf(jdkVersion_));
+        }
+
+        // -includes
+        if (!includes_.isEmpty()) {
+            args.add("-includes");
+            args.add(String.join(SEMICOLON, includes_));
+        }
+
+        // -languageVersion
+        if (languageVersion_ != null) {
+            args.add("-languageVersion");
+            args.add(languageVersion_);
+        }
+
+        // -noJdkLink
+        if (noJdkLink_) {
+            args.add("-noJdkLink");
+            args.add(String.valueOf(noJdkLink_));
+        }
+
+        // -noSkipEmptyPackages
+        if (noSkipEmptyPackages_) {
+            args.add("-noSkipEmptyPackages");
+            args.add(String.valueOf(noSkipEmptyPackages_));
+        }
+
+        // -noStdlibLink
+        if (noStdlibLink_) {
+            args.add("-noStdlibLink");
+            args.add(String.valueOf(noStdlibLink_));
+        }
+
+        // -reportUndocumented
+        if (reportUndocumented_) {
+            args.add("-reportUndocumented");
+            args.add(String.valueOf(reportUndocumented_));
+        }
+
+        // -perPackageOptions
+        if (!perPackageOptions_.isEmpty()) {
+            args.add("-perPackageOptions");
+            args.add(String.join(SEMICOLON, perPackageOptions_));
+        }
+
+        // -samples
+        if (!samples_.isEmpty()) {
+            args.add("-samples");
+            args.add(String.join(SEMICOLON, samples_));
+        }
+
+        // -skipDeprecated
+        if (skipDeprecated_) {
+            args.add("-skipDeprecated");
+            args.add(String.valueOf(skipDeprecated_));
+        }
+
         // -src
         if (!src_.isEmpty()) {
             args.add("-src");
-            src_.forEach(s -> args.add(s.getAbsolutePath() + ';'));
+            args.add(String.join(SEMICOLON, src_));
+        }
+
+        // -srcLinks
+        if (!srcLinks_.isEmpty()) {
+            args.add("-srcLinks");
+            var links = new ArrayList<String>();
+            srcLinks_.forEach((k, v) -> links.add(String.format("{%s}={%s}", k, v)));
+            args.add(String.join(SEMICOLON, links));
+        }
+
+        // -sourceSetName
+        if (sourceSetName_ != null) {
+            args.add("sourceSetName");
+            args.add(sourceSetName_);
+        }
+
+        // -suppressedFiles
+        if (!suppressedFiles_.isEmpty()) {
+            args.add("-suppressedFiles");
+            args.add(String.join(SEMICOLON, suppressedFiles_));
         }
 
         return args;
@@ -94,7 +222,7 @@ public class SourceSet {
      * @param classpath one or more classpath
      * @return this operation instance
      */
-    public SourceSet classpath(File... classpath) {
+    public SourceSet classpath(String... classpath) {
         classpath_.addAll(Arrays.asList(classpath));
         return this;
     }
@@ -105,7 +233,7 @@ public class SourceSet {
      * @param classpath the list of classpath
      * @return this operation instance
      */
-    public SourceSet classpath(Collection<File> classpath) {
+    public SourceSet classpath(Collection<String> classpath) {
         classpath_.addAll(classpath);
         return this;
     }
@@ -186,7 +314,7 @@ public class SourceSet {
      * @param files one or more files
      * @return this operation instance
      */
-    public SourceSet includes(File... files) {
+    public SourceSet includes(String... files) {
         includes_.addAll(Arrays.asList(files));
         return this;
     }
@@ -197,7 +325,7 @@ public class SourceSet {
      * @param files the list of files
      * @return this operation instance
      */
-    public SourceSet includss(Collection<File> files) {
+    public SourceSet includss(Collection<String> files) {
         includes_.addAll(files);
         return this;
     }
@@ -312,7 +440,7 @@ public class SourceSet {
      * @param samples the list of samples
      * @return this operation instance
      */
-    public SourceSet samples(Collection<File> samples) {
+    public SourceSet samples(Collection<String> samples) {
         samples_.addAll(samples);
         return this;
     }
@@ -323,7 +451,7 @@ public class SourceSet {
      * @param samples nne or more samples
      * @return this operation instance
      */
-    public SourceSet samples(File... samples) {
+    public SourceSet samples(String... samples) {
         samples_.addAll(List.of(samples));
         return this;
     }
@@ -356,7 +484,7 @@ public class SourceSet {
      * @param src the list of source code roots
      * @return this operation instance
      */
-    public SourceSet src(Collection<File> src) {
+    public SourceSet src(Collection<String> src) {
         src_.addAll(src);
         return this;
     }
@@ -367,7 +495,7 @@ public class SourceSet {
      * @param src pne ore moe source code roots
      * @return this operation instance
      */
-    public SourceSet src(File... src) {
+    public SourceSet src(String... src) {
         src_.addAll(List.of(src));
         return this;
     }
@@ -391,7 +519,7 @@ public class SourceSet {
      * @param suppressedFiles the list of suppressed files
      * @return this operation instance
      */
-    public SourceSet suppressedFiles(Collection<File> suppressedFiles) {
+    public SourceSet suppressedFiles(Collection<String> suppressedFiles) {
         suppressedFiles_.addAll(suppressedFiles);
         return this;
     }
@@ -402,7 +530,7 @@ public class SourceSet {
      * @param suppressedFiles one or moe suppressed files
      * @return this operation instance
      */
-    public SourceSet suppressedFiles(File... suppressedFiles) {
+    public SourceSet suppressedFiles(String... suppressedFiles) {
         suppressedFiles_.addAll(Arrays.asList(suppressedFiles));
         return this;
     }