Added more Dokka options

2023-11-05 06:40:58 -08:00 · 2023-11-05 06:40:58 -08:00 · 79254d9642
commit 79254d9642
parent 2e9e2bc826
6 changed files with 298 additions and 36 deletions
--- 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.
--- 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>
--- 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();
    }
 }
--- 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)
--- 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_));
+        }

        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;
    }
--- 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;
    }