argFile() {
- return argFile_;
- }
-
/**
* Returns the formatted arguments.
*
@@ -198,13 +153,13 @@ public class CompileOptions {
// @argfile
if (!argFile_.isEmpty()) {
- argFile_.forEach(f -> args.add("@" + f.getAbsolutePath()));
+ argFile_.forEach(f -> args.add("@" + f));
}
// classpath
if (!classpath_.isEmpty()) {
args.add("-classpath");
- args.add(classpath_.stream().map(File::getAbsolutePath).collect(Collectors.joining(File.pathSeparator)));
+ args.add(String.join(File.pathSeparator, classpath_));
}
// expression
@@ -230,9 +185,9 @@ public class CompileOptions {
}
// jdk-home
- if (jdkHome_ != null) {
+ if (isNotBlank(jdkHome_)) {
args.add("-jdk-home");
- args.add(jdkHome_.getAbsolutePath());
+ args.add(jdkHome_);
}
// jdk-release
@@ -246,9 +201,9 @@ public class CompileOptions {
}
// kotlin-home
- if (kotlinHome_ != null) {
+ if (isNotBlank(kotlinHome_)) {
args.add("-kotlin-home");
- args.add(kotlinHome_.getAbsolutePath());
+ args.add(kotlinHome_);
}
// language-version
@@ -295,9 +250,9 @@ public class CompileOptions {
}
// path
- if (path_ != null) {
+ if (isNotBlank(path_)) {
args.add("-d");
- args.add(path_.getAbsolutePath());
+ args.add(path_);
}
// plugin
@@ -343,8 +298,8 @@ public class CompileOptions {
* @param paths one pr more paths
* @return this operation instance
*/
- public CompileOptions classpath(String... paths) {
- classpath_.addAll(Arrays.stream(paths).map(File::new).toList());
+ public CompileKotlinOptions classpath(String... paths) {
+ Collections.addAll(classpath_, paths);
return this;
}
@@ -353,43 +308,21 @@ public class CompileOptions {
*
* The classpath can contain file and directory paths, ZIP, or JAR files.
*
- * @param paths one or more path
+ * @param paths the list of paths
* @return this operation instance
*/
- public CompileOptions classpath(File... paths) {
- classpath_.addAll(List.of(paths));
- return this;
- }
-
- /**
- * Search for class files in the specified paths.
- *
- * The classpath can contain file and directory paths, ZIP, or JAR files.
- *
- * @param paths the search paths
- * @return this operation instance
- */
- public CompileOptions classpath(Collection paths) {
+ public CompileKotlinOptions classpath(Collection paths) {
classpath_.addAll(paths);
return this;
}
- /**
- * Retrieves the class files classpath.
- *
- * @return the class files classpath
- */
- public Collection classpath() {
- return classpath_;
- }
-
/**
* Evaluate the given string as a Kotlin script.
*
* @param expression the expression
* @return this operation instance
*/
- public CompileOptions expression(String expression) {
+ public CompileKotlinOptions expression(String expression) {
expression_ = expression;
return this;
}
@@ -410,27 +343,18 @@ public class CompileOptions {
* @param includeRuntime {@code true} or {@code false}
* @return this operation instance
*/
- public CompileOptions includeRuntime(boolean includeRuntime) {
+ public CompileKotlinOptions includeRuntime(boolean includeRuntime) {
includeRuntime_ = includeRuntime;
return this;
}
- /**
- * Indicates whether {@link #verbose(boolean)} was set.
- *
- * @return {@code true} if verbose was set; or {@code false} otherwise
- */
- public boolean isVerbose() {
- return verbose_;
- }
-
/**
* Generate metadata for Java 1.8 reflection on method parameters.
*
* @param javaParameters {@code true} or {@code false}
* @return this operation instance
*/
- public CompileOptions javaParameters(boolean javaParameters) {
+ public CompileKotlinOptions javaParameters(boolean javaParameters) {
javaParameters_ = javaParameters;
return this;
}
@@ -441,18 +365,7 @@ public class CompileOptions {
* @param jdkHome the JDK home path
* @return this operation instance
*/
- public CompileOptions jdkHome(String jdkHome) {
- jdkHome_ = new File(jdkHome);
- return this;
- }
-
- /**
- * Use a custom JDK home directory to include into the classpath if it differs from the default {@code JAVA_HOME}.
- *
- * @param jdkHome the JDK home path
- * @return this operation instance
- */
- public CompileOptions jdkHome(File jdkHome) {
+ public CompileKotlinOptions jdkHome(String jdkHome) {
jdkHome_ = jdkHome;
return this;
}
@@ -468,7 +381,7 @@ public class CompileOptions {
* @param version the target version
* @return this operation instance
*/
- public CompileOptions jdkRelease(String version) {
+ public CompileKotlinOptions jdkRelease(String version) {
jdkRelease_ = version;
return this;
}
@@ -480,7 +393,7 @@ public class CompileOptions {
* @return this operation instance
* @see #jdkRelease(String)
*/
- public CompileOptions jdkRelease(int version) {
+ public CompileKotlinOptions jdkRelease(int version) {
jdkRelease_ = String.valueOf(version);
return this;
}
@@ -491,27 +404,18 @@ public class CompileOptions {
* @param jvmOptions one or more JVM option
* @return this operation instance
*/
- public CompileOptions jvmOptions(String... jvmOptions) {
- jvmOptions_.addAll(List.of(jvmOptions));
+ public CompileKotlinOptions jvmOptions(String... jvmOptions) {
+ Collections.addAll(jvmOptions_, jvmOptions);
return this;
}
/**
- * Retrieves the Java Virtual Machine options.
+ * Pass an option directly to JVM
*
- * @return the JVM options
- */
- public Collection jvmOptions() {
- return jvmOptions_;
- }
-
- /**
- * Pass an option directly to Java Virtual Machine
- *
- * @param jvmOptions the JVM options
+ * @param jvmOptions the list JVM options
* @return this operation instance
*/
- public CompileOptions jvmOptions(Collection jvmOptions) {
+ public CompileKotlinOptions jvmOptions(Collection jvmOptions) {
jvmOptions_.addAll(jvmOptions);
return this;
}
@@ -524,7 +428,7 @@ public class CompileOptions {
* @param target the target version
* @return this operation instance
*/
- public CompileOptions jvmTarget(String target) {
+ public CompileKotlinOptions jvmTarget(String target) {
jvmTarget_ = target;
return this;
}
@@ -536,7 +440,7 @@ public class CompileOptions {
* @return this operation instance
* @see #jvmTarget(String)
*/
- public CompileOptions jvmTarget(int target) {
+ public CompileKotlinOptions jvmTarget(int target) {
jvmTarget_ = String.valueOf(target);
return this;
}
@@ -547,29 +451,18 @@ public class CompileOptions {
* @param path the Kotlin home path
* @return this operation instance
*/
- public CompileOptions kotlinHome(File path) {
+ public CompileKotlinOptions kotlinHome(String path) {
kotlinHome_ = path;
return this;
}
- /**
- * Specify a custom path to the Kotlin compiler used for the discovery of runtime libraries.
- *
- * @param path the Kotlin home path
- * @return this operation instance
- */
- public CompileOptions kotlinHome(String path) {
- kotlinHome_ = new File(path);
- return this;
- }
-
/**
* Provide source compatibility with the specified version of Kotlin.
*
* @param version the language version
* @return this operation instance
*/
- public CompileOptions languageVersion(String version) {
+ public CompileKotlinOptions languageVersion(String version) {
languageVersion_ = version;
return this;
}
@@ -580,7 +473,7 @@ public class CompileOptions {
* @param name the module name
* @return this operation instance
*/
- public CompileOptions moduleName(String name) {
+ public CompileKotlinOptions moduleName(String name) {
moduleName_ = name;
return this;
}
@@ -591,7 +484,7 @@ public class CompileOptions {
* @param noJdk {@code true} or {@code false}
* @return this operation instance
*/
- public CompileOptions noJdk(boolean noJdk) {
+ public CompileKotlinOptions noJdk(boolean noJdk) {
noJdk_ = noJdk;
return this;
}
@@ -602,7 +495,7 @@ public class CompileOptions {
* @param noReflect {@code true} or {@code false}
* @return this operation instance
*/
- public CompileOptions noReflect(boolean noReflect) {
+ public CompileKotlinOptions noReflect(boolean noReflect) {
noReflect_ = noReflect;
return this;
}
@@ -614,7 +507,7 @@ public class CompileOptions {
* @param noStdLib {@code true} or {@code false}
* @return this operation instance
*/
- public CompileOptions noStdLib(boolean noStdLib) {
+ public CompileKotlinOptions noStdLib(boolean noStdLib) {
noStdLib_ = noStdLib;
return this;
}
@@ -625,7 +518,7 @@ public class CompileOptions {
* @param noWarn {@code true} or {@code false}
* @return this operation instance
*/
- public CompileOptions noWarn(boolean noWarn) {
+ public CompileKotlinOptions noWarn(boolean noWarn) {
noWarn_ = noWarn;
return this;
}
@@ -636,27 +529,18 @@ public class CompileOptions {
* @param annotations one or more annotation names
* @return this operation instance
*/
- public CompileOptions optIn(String... annotations) {
- optIn_.addAll(List.of(annotations));
+ public CompileKotlinOptions optIn(String... annotations) {
+ Collections.addAll(optIn_, annotations);
return this;
}
- /**
- * Retrieves the opt-in fully qualified names.
- *
- * @return the fully qualified names
- */
- public Collection optIn() {
- return optIn_;
- }
-
/**
* Enable usages of API that requires opt-in with a requirement annotation with the given fully qualified name.
*
- * @param annotations the annotation names
+ * @param annotations list of annotation names
* @return this operation instance
*/
- public CompileOptions optIn(Collection annotations) {
+ public CompileKotlinOptions optIn(Collection annotations) {
optIn_.addAll(annotations);
return this;
}
@@ -667,27 +551,18 @@ public class CompileOptions {
* @param options one or more compiler options
* @return this operation instance
*/
- public CompileOptions options(String... options) {
- options_.addAll(List.of(options));
+ public CompileKotlinOptions options(String... options) {
+ Collections.addAll(options_, options);
return this;
}
- /**
- * Retrieves additional compiler options.
- *
- * @return the compiler options
- */
- public Collection options() {
- return options_;
- }
-
/**
* Specify additional compiler options.
*
- * @param options the compiler options
+ * @param options list of compiler options
* @return this operation instance
*/
- public CompileOptions options(Collection options) {
+ public CompileKotlinOptions options(Collection options) {
options_.addAll(options);
return this;
}
@@ -700,8 +575,8 @@ public class CompileOptions {
* @param path the location path
* @return this operation instance
*/
- public CompileOptions path(File path) {
- path_ = path;
+ public CompileKotlinOptions path(File path) {
+ path_ = path.getAbsolutePath();
return this;
}
@@ -713,8 +588,8 @@ public class CompileOptions {
* @param path the location path
* @return this operation instance
*/
- public CompileOptions path(String path) {
- path_ = new File(path);
+ public CompileKotlinOptions path(String path) {
+ path_ = path;
return this;
}
@@ -726,27 +601,18 @@ public class CompileOptions {
* @param value the plugin option value
* @return this operation instance
*/
- public CompileOptions plugin(String id, String optionName, String value) {
+ public CompileKotlinOptions plugin(String id, String optionName, String value) {
plugin_.add(id + ':' + optionName + ':' + value);
return this;
}
- /**
- * Retrieves the plugin options.
- *
- * @return the plugin ofoptions.
- */
- public Collection plugin() {
- return plugin_;
- }
-
/**
* Allow using declarations only from the specified version of Kotlin bundled libraries.
*
* @param progressive {@code true} or {@code false}
* @return this operation instance
*/
- public CompileOptions progressive(boolean progressive) {
+ public CompileKotlinOptions progressive(boolean progressive) {
progressive_ = progressive;
return this;
}
@@ -759,29 +625,20 @@ public class CompileOptions {
* @param classNames one or more class names
* @return this operation instance
*/
- public CompileOptions scriptTemplates(String... classNames) {
- scriptTemplates_.addAll(List.of(classNames));
+ public CompileKotlinOptions scriptTemplates(String... classNames) {
+ Collections.addAll(scriptTemplates_, classNames);
return this;
}
- /**
- * Retrieves the script templates.
- *
- * @return the script templates.
- */
- public Collection scriptTemplates() {
- return scriptTemplates_;
- }
-
/**
* Script definition template classes.
*
* Use fully qualified class names.
*
- * @param classNames the class names
+ * @param classNames the list class names
* @return this operation instance
*/
- public CompileOptions scriptTemplates(Collection classNames) {
+ public CompileKotlinOptions scriptTemplates(Collection classNames) {
scriptTemplates_.addAll(classNames);
return this;
}
@@ -792,7 +649,7 @@ public class CompileOptions {
* @param verbose {@code true} or {@code false}
* @return this operation instance
*/
- public CompileOptions verbose(boolean verbose) {
+ public CompileKotlinOptions verbose(boolean verbose) {
verbose_ = verbose;
return this;
}
@@ -803,7 +660,7 @@ public class CompileOptions {
* @param wError {@code true} or {@code false}
* @return this operation instance
*/
- public CompileOptions wError(boolean wError) {
+ public CompileKotlinOptions wError(boolean wError) {
wError_ = wError;
return this;
}
diff --git a/src/main/java/rife/bld/extension/kotlin/CompilerPlugin.java b/src/main/java/rife/bld/extension/CompileKotlinPlugin.java
similarity index 58%
rename from src/main/java/rife/bld/extension/kotlin/CompilerPlugin.java
rename to src/main/java/rife/bld/extension/CompileKotlinPlugin.java
index 7a3d94e..47264b3 100644
--- a/src/main/java/rife/bld/extension/kotlin/CompilerPlugin.java
+++ b/src/main/java/rife/bld/extension/CompileKotlinPlugin.java
@@ -14,7 +14,7 @@
* limitations under the License.
*/
-package rife.bld.extension.kotlin;
+package rife.bld.extension;
/**
* Defines the known Kotlin compiler plugins match (regex) strings.
@@ -22,18 +22,20 @@ package rife.bld.extension.kotlin;
* @author Erik C. Thauvin
* @since 1.0
*/
-public enum CompilerPlugin {
- ALL_OPEN("^kotlin-allopen-compiler-plugin-.*$"),
- ASSIGNMENT("^kotlin-assignment-compiler-plugin-.*$"),
+public enum CompileKotlinPlugin {
+ ALL_OPEN("^allopen-compiler-plugin-.*$"),
+ ASSIGNMENT("^assignment-compiler-plugin-.*$"),
+ KOTLIN_IMPORTS_DUMPER("^kotlin-imports-dumper-compiler-plugin-.*$"),
KOTLIN_SERIALIZATION("^kotlin-serialization-compiler-plugin-.*$"),
- LOMBOK("^kotlin-lombok-compiler-plugin-.*$"),
- NOARG("^kotlin-noarg-compiler-plugin-.*$"),
- POWER_ASSERT("^kotlin-power-assert-compiler-plugin-.*$"),
- SAM_WITH_RECEIVER("^kotlin-sam-with-receiver-compiler-plugin-.*$");
+ KOTLINX_SERIALIZATION("^kotlinx-serialization-compiler-plugin-.*$"),
+ LOMBOK("^lombok-compiler-plugin-.*$"),
+ NOARG("^noarg-compiler-plugin-.*$"),
+ POWER_ASSERT("^power-assert-compiler-plugin-.*$"),
+ SAM_WITH_RECEIVER("^sam-with-receiver-compiler-plugin-.*$");
- public final String regex;
+ public final String label;
- CompilerPlugin(String regex) {
- this.regex = regex;
+ CompileKotlinPlugin(String label) {
+ this.label = label;
}
}
diff --git a/src/main/java/rife/bld/extension/dokka/AnalysisPlatform.java b/src/main/java/rife/bld/extension/dokka/AnalysisPlatform.java
new file mode 100644
index 0000000..dd6ff1a
--- /dev/null
+++ b/src/main/java/rife/bld/extension/dokka/AnalysisPlatform.java
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2023-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package rife.bld.extension.dokka;
+
+/**
+ * Dokka's analysis platforms.
+ *
+ * @author Erik C. Thauvin
+ * @since 1.0
+ */
+public enum AnalysisPlatform {
+ JVM, JS, NATIVE, COMMON, ANDROID
+}
diff --git a/src/main/java/rife/bld/extension/dokka/DocumentedVisibility.java b/src/main/java/rife/bld/extension/dokka/DocumentedVisibility.java
new file mode 100644
index 0000000..dae65a4
--- /dev/null
+++ b/src/main/java/rife/bld/extension/dokka/DocumentedVisibility.java
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2023-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package rife.bld.extension.dokka;
+
+/**
+ * Dokka documented visibilities.
+ *
+ * @author Erik C. Thauvin
+ * @since 1.0
+ */
+public enum DocumentedVisibility {
+ PUBLIC, PRIVATE, PROTECTED, INTERNAL, PACKAGE
+}
diff --git a/src/main/java/rife/bld/extension/dokka/DokkaOperation.java b/src/main/java/rife/bld/extension/dokka/DokkaOperation.java
new file mode 100644
index 0000000..56d2661
--- /dev/null
+++ b/src/main/java/rife/bld/extension/dokka/DokkaOperation.java
@@ -0,0 +1,609 @@
+/*
+ * Copyright 2023-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package rife.bld.extension.dokka;
+
+import rife.bld.BaseProject;
+import rife.bld.extension.CompileKotlinOperation;
+import rife.bld.operations.AbstractProcessOperation;
+import rife.tools.StringUtils;
+
+import java.io.File;
+import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+import static rife.bld.extension.CompileKotlinOperation.isNotBlank;
+
+/**
+ * Builds documentation (javadoc, HTML, etc.) using Dokka.
+ *
+ * @author Erik C. Thauvin
+ * @since 1.0
+ */
+@SuppressWarnings("PMD.AvoidThrowingRawExceptionTypes")
+public class DokkaOperation extends AbstractProcessOperation {
+ private final static String GFM_PLUGIN_REGEXP =
+ "^.*(dokka-base|analysis-kotlin-descriptors|gfm-plugin|freemarker).*\\.jar$";
+ private final static String HTML_PLUGIN_REGEXP =
+ "^.*(dokka-base|analysis-kotlin-descriptors|kotlinx-html-jvm|freemarker).*\\.jar$";
+ private final static String JAVADOC_PLUGIN_REGEXP =
+ "^.*(dokka-base|analysis-kotlin-descriptors|javadoc-plugin|kotlin-as-java-plugin|korte-jvm).*\\.jar$";
+ private final static String JEKYLL_PLUGIN_REGEXP =
+ "^.*(dokka-base|analysis-kotlin-descriptors|jekyll-plugin|gfm-plugin|freemarker).*\\.jar$";
+ private final Logger LOGGER = Logger.getLogger(DokkaOperation.class.getName());
+ private final Map globalLinks_ = new ConcurrentHashMap<>();
+ private final Collection globalPackageOptions_ = new ArrayList<>();
+ private final Collection globalSrcLinks_ = new ArrayList<>();
+ private final Collection includes_ = new ArrayList<>();
+ private final Collection pluginsClasspath_ = new ArrayList<>();
+ private final Map pluginsConfiguration_ = new ConcurrentHashMap<>();
+ private boolean delayTemplateSubstitution_;
+ private boolean failOnWarning_;
+ private File json;
+ private LoggingLevel loggingLevel_;
+ private String moduleName_;
+ private String moduleVersion_;
+ private boolean noSuppressObviousFunctions_;
+ private boolean offlineMode_;
+ private File outputDir_;
+ private BaseProject project_;
+ private SourceSet sourceSet_;
+ private boolean suppressInheritedMembers_;
+
+ // Encodes to JSON adding braces as needed
+ private static String encodeJson(final String json) {
+ var sb = new StringBuilder(json);
+ if (!json.startsWith("{") || !json.endsWith("}")) {
+ sb.insert(0, "{").append('}');
+ }
+ return StringUtils.encodeJson(sb.toString());
+ }
+
+ /**
+ * Sets the delay substitution of some elements.
+ *
+ * Used in incremental builds of multimodule projects.
+ *
+ * @param delayTemplateSubstitution the delay
+ * @return this operation instance
+ */
+ public DokkaOperation delayTemplateSubstitution(Boolean delayTemplateSubstitution) {
+ delayTemplateSubstitution_ = delayTemplateSubstitution;
+ return this;
+ }
+
+ /**
+ * Part of the {@link #execute execute} operation, constructs the command list to use for building the process.
+ *
+ * @since 1.5
+ */
+ @Override
+ protected List executeConstructProcessCommandList() {
+ if (project_ == null) {
+ throw new IllegalArgumentException("A project must be specified.");
+ }
+
+ final List args = new ArrayList<>();
+
+ // java
+ args.add(javaTool());
+
+ var cli = CompileKotlinOperation.getJarList(project_.libBldDirectory(), "^.*dokka-cli.*\\.jar$");
+
+ if (cli.size() != 1) {
+ throw new RuntimeException("The dokka-cli JAR could not be found.");
+ }
+
+ // -jar dokka-cli
+ args.add("-jar");
+ args.add(cli.get(0));
+
+ // -pluginClasspath
+ if (!pluginsClasspath_.isEmpty()) {
+ args.add("-pluginsClasspath");
+ args.add(String.join(";", pluginsClasspath_));
+ }
+
+ // -sourceSet
+ var sourceSetArgs = sourceSet_.args();
+ if (sourceSetArgs.isEmpty()) {
+ throw new IllegalArgumentException("At least one sourceSet is required.");
+ } else {
+ args.add("-sourceSet");
+ args.add(String.join(" ", sourceSet_.args()));
+ }
+
+ // -outputDir
+ if (outputDir_ != null) {
+ if (!outputDir_.exists() && !outputDir_.mkdirs()) {
+ throw new RuntimeException("Could not create: " + outputDir_.getAbsolutePath());
+ }
+
+ args.add("-outputDir");
+ args.add(outputDir_.getAbsolutePath());
+ }
+
+ // -delayTemplateSubstitution
+ if (delayTemplateSubstitution_) {
+ args.add("-delayTemplateSubstitution");
+ }
+
+ // -failOnWarning
+ if (failOnWarning_) {
+ args.add("-failOnWarning");
+ }
+
+ // -globalLinks_
+ if (!globalLinks_.isEmpty()) {
+ args.add("-globalLinks");
+ var links = new ArrayList();
+ 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 (isNotBlank(moduleName_)) {
+ args.add("-moduleName");
+ args.add(moduleName_);
+ }
+
+ // -moduleVersion
+ if (isNotBlank(moduleVersion_)) {
+ args.add("-moduleVersion");
+ args.add(moduleVersion_);
+ }
+
+ // -noSuppressObviousFunctions
+ if (noSuppressObviousFunctions_) {
+ args.add("-noSuppressObviousFunctions");
+ }
+
+ // -offlineMode
+ if (offlineMode_) {
+ args.add("-offlineMode");
+ }
+
+ // -pluginConfiguration
+ if (!pluginsConfiguration_.isEmpty()) {
+ args.add("-pluginsConfiguration");
+ var confs = new ArrayList();
+ pluginsConfiguration_.forEach((k, v) ->
+ confs.add(String.format("%s=%s", encodeJson(k), encodeJson(v))));
+ args.add(String.join("^^", confs));
+ }
+
+ // -suppressInheritedMembers
+ if (suppressInheritedMembers_) {
+ args.add("-suppressInheritedMembers");
+ }
+
+ // json
+ if (json != null) {
+ args.add(json.getAbsolutePath());
+ }
+
+ if (LOGGER.isLoggable(Level.FINE)) {
+ LOGGER.fine(String.join(" ", args));
+ }
+
+ return args;
+ }
+
+ /**
+ * Configures the operation from a {@link BaseProject}.
+ *
+ * Sets the {@link #sourceSet sourceSet}, {@link SourceSet#jdkVersion jdkVersion}, {@link #moduleName moduleName}
+ * and {@link SourceSet#classpath(String...) classpath} from the project.
+ *
+ * @param project the project to configure the operation from
+ */
+ @Override
+ public DokkaOperation fromProject(BaseProject project) {
+ project_ = project;
+ sourceSet_ = new SourceSet()
+ .src(new File(project.srcMainDirectory(), "kotlin").getAbsolutePath())
+ .classpath(project.compileClasspathJars())
+ .classpath(project.providedClasspathJars());
+ if (project.javaRelease() != null) {
+ sourceSet_ = sourceSet_.jdkVersion(project.javaRelease());
+ }
+ moduleName_ = project.name();
+ return this;
+ }
+
+ /**
+ * Sets whether to fail documentation generation if Dokka has emitted a warning or an error.
+ *
+ * Whether to fail documentation generation if Dokka has emitted a warning or an error. The process waits until all
+ * errors and warnings have been emitted first.
+ *
+ * This setting works well with {@link SourceSet#reportUndocumented}
+ *
+ * @param failOnWarning {@code true} or {@code false}
+ * @return this operation instance
+ */
+ public DokkaOperation failOnWarning(Boolean failOnWarning) {
+ failOnWarning_ = failOnWarning;
+ return this;
+ }
+
+ /**
+ * Set the global external documentation links.
+ *
+ * @param url the external documentation URL
+ * @param packageListUrl the external documentation package list URL
+ * @return this operation instance
+ */
+ public DokkaOperation globalLinks(String url, String packageListUrl) {
+ globalLinks_.put(url, packageListUrl);
+ return this;
+ }
+
+ /**
+ * Set the global external documentation links.
+ *
+ * @param globalLinks the map of global links
+ * @return this operation instance
+ * @see #globalSrcLink(String...) #globalSrcLink(String...)#globalSrcLink(String...)
+ */
+ public DokkaOperation globalLinks(Map globalLinks) {
+ globalLinks_.putAll(globalLinks);
+ return this;
+ }
+
+ /**
+ * Sets the global list of package configurations.
+ *
+ * Using format:
+ *
+ * - matchingRegexp
+ * - -deprecated
+ * - -privateApi
+ * - +warnUndocumented
+ * - +suppress
+ * - +visibility:PUBLIC
+ * - ...
+ *
+ *
+ * @param options ome pr more package configurations
+ * @return this operation instance
+ */
+ public DokkaOperation globalPackageOptions(String... options) {
+ Collections.addAll(globalPackageOptions_, options);
+ return this;
+ }
+
+ /**
+ * Sets the global list of package configurations.
+ *
+ * Using format:
+ *
+ * - matchingRegexp
+ * - -deprecated
+ * - -privateApi
+ * - +warnUndocumented
+ * - +suppress
+ * - +visibility:PUBLIC
+ * - ...
+ *
+ *
+ * @param options the list of package configurations
+ * @return this operation instance
+ */
+ public DokkaOperation globalPackageOptions(Collection options) {
+ globalPackageOptions_.addAll(options);
+ return this;
+ }
+
+ /**
+ * Sets the global mapping between a source directory and a Web service for browsing the code.
+ *
+ * @param links one or more links mapping
+ * @return this operation instance
+ */
+ public DokkaOperation globalSrcLink(String... links) {
+ Collections.addAll(globalSrcLinks_, links);
+ return this;
+ }
+
+ /**
+ * Sets the global mapping between a source directory and a Web service for browsing the code.
+ *
+ * @param links the links mapping
+ * @return this operation instance
+ */
+ public DokkaOperation globalSrcLink(Collection links) {
+ globalSrcLinks_.addAll(links);
+ return this;
+ }
+
+ /**
+ * Sets the Markdown files that contain module and package documentation.
+ *
+ * The contents of specified files are parsed and embedded into documentation as module and package descriptions.
+ *
+ * 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_, files);
+ return this;
+ }
+
+ /**
+ * Sets the Markdown files that contain module and package documentation.
+ *
+ * The contents of specified files are parsed and embedded into documentation as module and package descriptions.
+ *
+ * This can be configured on per-package basis.
+ *
+ * @param files the list of files
+ * @return this operation instance
+ */
+ public DokkaOperation includes(Collection files) {
+ includes_.addAll(files);
+ return this;
+ }
+
+ /**
+ * JSON configuration file path.
+ *
+ * @param configuration the configuration file path
+ */
+ public DokkaOperation json(File configuration) {
+ json = configuration;
+ return this;
+ }
+
+ /**
+ * Sets the logging level.
+ *
+ * @param loggingLevel the logging level
+ * @return this operation instance
+ */
+ public DokkaOperation loggingLevel(LoggingLevel loggingLevel) {
+ loggingLevel_ = loggingLevel;
+ return this;
+ }
+
+ /**
+ * Sets the name of the project/module. Default is {@code root}.
+ *
+ * The display name used to refer to the module. It is used for the table of contents, navigation, logging, etc.
+ *
+ * @param moduleName the project/module name
+ * @return this operation instance
+ */
+ public DokkaOperation moduleName(String moduleName) {
+ moduleName_ = moduleName;
+ return this;
+ }
+
+ /**
+ * Set the documented version.
+ *
+ * @param version the version
+ * @return this operation instance
+ */
+ public DokkaOperation moduleVersion(String version) {
+ moduleVersion_ = version;
+ return this;
+ }
+
+ /**
+ * Sets whether to suppress obvious functions such as inherited from
+ * kotlin.Any and {@link java.lang.Object}.
+ *
+ * A function is considered to be obvious if it is:
+ *
+ * - Inherited from kotlin.Any,
+ * Kotlin.Enum, {@link java.lang.Object}
+ * or {@link java.lang.Enum}, such as {@code equals}, {@code hashCode}, {@code toString}.
+ *
- Synthetic (generated by the compiler) and does not have any documentation, such as
+ * {@code dataClass.componentN} or {@code dataClass.copy}.
+ *
+ *
+ * @param noSuppressObviousFunctions {@code true} or {@code false}
+ * @return this operation instance
+ */
+ public DokkaOperation noSuppressObviousFunctions(Boolean noSuppressObviousFunctions) {
+ noSuppressObviousFunctions_ = noSuppressObviousFunctions;
+ return this;
+ }
+
+ /**
+ * Sets whether to resolve remote files/links over network.
+ *
+ * This includes package-lists used for generating external documentation links. For example, to make classes from
+ * the standard library clickable.
+ *
+ * Setting this to true can significantly speed up build times in certain cases, but can also worsen documentation
+ * quality and user experience. For example, by not resolving class/member links from your dependencies, including
+ * the standard library.
+ *
+ * Note: You can cache fetched files locally and provide them to Dokka as local paths.
+ *
+ * @param offlineMode the offline mode
+ * @return this operation instance
+ * @see SourceSet#externalDocumentationLinks(String, String)
+ */
+ public DokkaOperation offlineMode(Boolean offlineMode) {
+ offlineMode_ = offlineMode;
+ return this;
+ }
+
+ /**
+ * Sets the output directory path, {@code ./dokka} by default.
+ *
+ * The directory to where documentation is generated, regardless of output format.
+ *
+ * @param outputDir the output directory
+ * @return this operation instance
+ */
+ public DokkaOperation outputDir(File outputDir) {
+ outputDir_ = outputDir;
+ return this;
+ }
+
+ /**
+ * Sets the output directory path, {@code ./dokka} by default.
+ *
+ * The directory to where documentation is generated, regardless of output format.
+ *
+ * @param outputDir the output directory
+ * @return this operation instance
+ */
+ public DokkaOperation outputDir(String outputDir) {
+ outputDir_ = new File(outputDir);
+ return this;
+ }
+
+ /**
+ * Sets the Dokka {@link OutputFormat output format}.
+ *
+ * @param format The {@link OutputFormat output format}
+ * @return this operation instance
+ */
+ public DokkaOperation outputFormat(OutputFormat format) {
+ pluginsClasspath_.clear();
+ if (format.equals(OutputFormat.JAVADOC)) {
+ pluginsClasspath_.addAll(CompileKotlinOperation.getJarList(project_.libBldDirectory(),
+ JAVADOC_PLUGIN_REGEXP));
+ } else if (format.equals(OutputFormat.HTML)) {
+ pluginsClasspath_.addAll(CompileKotlinOperation.getJarList(project_.libBldDirectory(),
+ HTML_PLUGIN_REGEXP));
+ } else if (format.equals(OutputFormat.MARKDOWN)) {
+ pluginsClasspath_.addAll(CompileKotlinOperation.getJarList(project_.libBldDirectory(),
+ GFM_PLUGIN_REGEXP));
+ } else if (format.equals(OutputFormat.JEKYLL)) {
+ pluginsClasspath_.addAll(CompileKotlinOperation.getJarList(project_.libBldDirectory(),
+ JEKYLL_PLUGIN_REGEXP));
+ }
+ return this;
+ }
+
+ /**
+ * Sets the configuration for Dokka plugins.
+ *
+ * @param name The fully-qualified plugin name
+ * @param jsonConfiguration The plugin JSON configuration
+ * @return this operation instance
+ */
+ public DokkaOperation pluginConfigurations(String name, String jsonConfiguration) {
+ pluginsConfiguration_.put(name, jsonConfiguration);
+ return this;
+ }
+
+ /**
+ * Sets the configuration for Dokka plugins.
+ *
+ * @param pluginConfiguratione the map of configurations
+ * @return this operation instance
+ * @see #pluginConfigurations(String, String)
+ */
+ public DokkaOperation pluginConfigurations(Map pluginConfiguratione) {
+ pluginsConfiguration_.putAll(pluginConfiguratione);
+ return this;
+ }
+
+ /**
+ * Sets the list of jars with Dokka plugins and their dependencies.
+ *
+ * @param jars one or more jars
+ * @return this operation instance
+ */
+ public DokkaOperation pluginsClasspath(String... jars) {
+ Collections.addAll(pluginsClasspath_, jars);
+ return this;
+ }
+
+ /**
+ * 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 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.
+ *
+ * Individual and additional configuration of Kotlin source sets.
+ *
+ * @param sourceSet the source set configurations
+ * @return this operation instance
+ */
+ public DokkaOperation sourceSet(SourceSet sourceSet) {
+ sourceSet_ = sourceSet;
+ return this;
+ }
+
+ /**
+ * Sets whether to suppress inherited members that aren't explicitly overridden in a given class.
+ *
+ * @param suppressInheritedMembers {@code true} or {@code false}
+ * @return this operation instance
+ */
+ public DokkaOperation suppressInheritedMembers(Boolean suppressInheritedMembers) {
+ suppressInheritedMembers_ = suppressInheritedMembers;
+ return this;
+ }
+}
diff --git a/src/main/java/rife/bld/extension/dokka/LoggingLevel.java b/src/main/java/rife/bld/extension/dokka/LoggingLevel.java
new file mode 100644
index 0000000..b493e11
--- /dev/null
+++ b/src/main/java/rife/bld/extension/dokka/LoggingLevel.java
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2023-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package rife.bld.extension.dokka;
+
+/**
+ * Dokka logging levels.
+ *
+ * @author Erik C. Thauvin
+ * @since 1.0
+ */
+public enum LoggingLevel {
+ DEBUG, PROGRESS, INFO, WARN, ERROR
+}
diff --git a/src/main/java/rife/bld/extension/dokka/OutputFormat.java b/src/main/java/rife/bld/extension/dokka/OutputFormat.java
new file mode 100644
index 0000000..0d4a2c0
--- /dev/null
+++ b/src/main/java/rife/bld/extension/dokka/OutputFormat.java
@@ -0,0 +1,27 @@
+/*
+ * Copyright 2023-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package rife.bld.extension.dokka;
+
+/**
+ * Dokka output formats.
+ *
+ * @author Erik C. Thauvin
+ * @since 1.0
+ */
+public enum OutputFormat {
+ JAVADOC, JEKYLL, HTML, MARKDOWN
+}
diff --git a/src/main/java/rife/bld/extension/dokka/SourceSet.java b/src/main/java/rife/bld/extension/dokka/SourceSet.java
new file mode 100644
index 0000000..e9457b5
--- /dev/null
+++ b/src/main/java/rife/bld/extension/dokka/SourceSet.java
@@ -0,0 +1,680 @@
+/*
+ * Copyright 2023-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package rife.bld.extension.dokka;
+
+import java.io.File;
+import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Configuration for a Dokka source set.
+ *
+ * @author Erik C. Thauvin
+ * @since 1.0
+ */
+public class SourceSet {
+ private static final String SEMICOLON = ";";
+ private final Collection classpath_ = new ArrayList<>();
+ private final Map dependentSourceSets_ = new ConcurrentHashMap<>();
+ private final Collection documentedVisibilities_ = new ArrayList<>();
+ private final Map externalDocumentationLinks_ = new ConcurrentHashMap<>();
+ private final Collection includes_ = new ArrayList<>();
+ private final Collection perPackageOptions_ = new ArrayList<>();
+ private final Collection samples_ = new ArrayList<>();
+ private final Map srcLinks_ = new ConcurrentHashMap<>();
+ private final Collection src_ = new ArrayList<>();
+ private final Collection suppressedFiles_ = new ArrayList<>();
+ private AnalysisPlatform analysisPlatform_;
+ private String apiVersion_;
+ private String displayName_;
+ private String jdkVersion_;
+ private String languageVersion_;
+ private boolean noJdkLink_;
+ private boolean noSkipEmptyPackages_;
+ private boolean noStdlibLink_;
+ private boolean reportUndocumented_;
+ private boolean skipDeprecated_;
+ private String sourceSetName_;
+
+ /**
+ * Sets the platform used for setting up analysis. Default is {@link AnalysisPlatform#JVM JVM}
+ *
+ * Platform to be used for setting up code analysis and {@code @sample} environment.
+ *
+ * @param analysisPlatform the analysis platform
+ * @return this operation instance
+ */
+ public SourceSet analysisPlatform(AnalysisPlatform analysisPlatform) {
+ analysisPlatform_ = analysisPlatform;
+ return this;
+ }
+
+ /**
+ * Sets the Kotlin API version used for setting up analysis and samples.
+ *
+ * @param apiVersion the api version
+ * @return this operation instance
+ */
+ public SourceSet apiVersion(String apiVersion) {
+ apiVersion_ = apiVersion;
+ return this;
+ }
+
+ /**
+ * Sets the Kotlin API version used for setting up analysis and samples.
+ *
+ * @param apiVersion the api version
+ * @return this operation instance
+ */
+ public SourceSet apiVersion(int apiVersion) {
+ apiVersion_ = String.valueOf(apiVersion);
+ return this;
+ }
+
+ /**
+ * Returns the formatted arguments.
+ *
+ * @return the arguments
+ */
+ public List args() {
+ var args = new ArrayList();
+
+ // -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();
+ 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();
+ 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();
+ externalDocumentationLinks_.forEach((k, v) -> links.add(String.format("%s^%s", k, v)));
+ args.add(String.join("^^", links));
+ }
+
+ // -jdkVersion
+ if (jdkVersion_ != null) {
+ args.add("-jdkVersion");
+ args.add(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");
+ args.add(String.join(SEMICOLON, src_));
+ }
+
+ // -srcLink
+ if (!srcLinks_.isEmpty()) {
+ args.add("-srcLink");
+ var links = new ArrayList();
+ 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;
+ }
+
+ /**
+ * Sets classpath for analysis and interactive samples.
+ *
+ * This is useful if some types that come from dependencies are not resolved/picked up automatically.
+ *
+ * This option accepts both {@code .jar} and {@code .klib} files.
+ *
+ * @param files one or more file
+ * @return this operation instance
+ */
+ public SourceSet classpath(String... files) {
+ Collections.addAll(classpath_, files);
+ return this;
+ }
+
+ /**
+ * Sets classpath for analysis and interactive samples.
+ *
+ * This is useful if some types that come from dependencies are not resolved/picked up automatically.
+ *
+ * This option accepts both {@code .jar} and {@code .klib} files.
+ *
+ * @param files the list of files
+ * @return this operation instance
+ */
+ public SourceSet classpath(Collection files) {
+ classpath_.addAll(files);
+ return this;
+ }
+
+ /**
+ * Sets classpath for analysis and interactive samples.
+ *
+ * This is useful if some types that come from dependencies are not resolved/picked up automatically.
+ *
+ * This option accepts both {@code .jar} and {@code .klib} files.
+ *
+ * @param files the list of files
+ * @return this operation instance
+ */
+ public SourceSet classpath(List files) {
+ files.forEach(it -> classpath_.add(it.getAbsolutePath()));
+ return this;
+ }
+
+ /**
+ * Sets the names of dependent source sets.
+ *
+ * @param moduleName the module name
+ * @param sourceSetName the source set name
+ * @return this operation instance
+ */
+ public SourceSet dependentSourceSets(String moduleName, String sourceSetName) {
+ dependentSourceSets_.put(moduleName, sourceSetName);
+ return this;
+ }
+
+ /**
+ * Sets the names of dependent source sets.
+ *
+ * @param dependentSourceSets the map of dependent source set names
+ * @return this operation instance
+ * @see #dependentSourceSets(String, String)
+ */
+ public SourceSet dependentSourceSets(Map dependentSourceSets) {
+ dependentSourceSets_.putAll(dependentSourceSets);
+ return this;
+ }
+
+ /**
+ * Sets the display name of the source set, used both internally and externally.
+ *
+ * The name is used both externally (for example, the source set name is visible to documentation readers) and
+ * internally (for example, for logging messages of {@link #reportUndocumented reportUndocumented}).
+ *
+ * The platform name can be used if you don't have a better alternative.
+ *
+ * @param displayName the display name
+ * @return this operation instance
+ */
+ public SourceSet displayName(String displayName) {
+ displayName_ = displayName;
+ return this;
+ }
+
+ /**
+ * Sets visibilities to be documented.
+ *
+ * This can be used if you want to document protected/internal/private declarations, as well as if you want to
+ * exclude public declarations and only document internal API.
+ *
+ * This can be configured on per-package basis.
+ *
+ * @param visibilities one or more visibilities
+ * @return this operation instance
+ */
+ public SourceSet documentedVisibilities(DocumentedVisibility... visibilities) {
+ documentedVisibilities_.addAll(Arrays.asList(visibilities));
+ return this;
+ }
+
+ /**
+ * Sets the external documentation links.
+ *
+ * A set of parameters for external documentation links that is applied only for this source set.
+ *
+ * @param url the external documentation URL
+ * @param packageListUrl the external documentation package list URL
+ * @return this operation instance
+ */
+ public SourceSet externalDocumentationLinks(String url, String packageListUrl) {
+ externalDocumentationLinks_.put(url, packageListUrl);
+ return this;
+ }
+
+ /**
+ * Sets the external documentation links.
+ *
+ * A set of parameters for external documentation links that is applied only for this source set.
+ *
+ * @param externalDocumentationLinks the map of external documentation links
+ * @return this operation instance
+ * @see #externalDocumentationLinks(String, String)
+ */
+ public SourceSet externalDocumentationLinks(Map externalDocumentationLinks) {
+ externalDocumentationLinks_.putAll(externalDocumentationLinks);
+ return this;
+ }
+
+ /**
+ * Sets the Markdown files that contain module and package documentation.
+ *
+ * A list of Markdown files that contain module and package documentation.
+ *
+ * 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_, files);
+ return this;
+ }
+
+ /**
+ * Sets the Markdown files that contain module and package documentation.
+ *
+ * A list of Markdown files that contain module and package documentation.
+ *
+ * The contents of the specified files are parsed and embedded into documentation as module and package
+ * descriptions.
+ *
+ * @param files the list of files
+ * @return this operation instance
+ */
+ public SourceSet includes(Collection files) {
+ includes_.addAll(files);
+ return this;
+ }
+
+ /**
+ * Sets the version of JDK to use for linking to JDK Javadocs.
+ *
+ * The JDK version to use when generating external documentation links for Java types.
+ *
+ * For example, if you use {@link java.util.UUID} in some public declaration signature, and this option is set to 8,
+ * Dokka generates an external documentation link to JDK 8 Javadocs for it.
+ *
+ * @param jdkVersion the JDK version
+ * @return this operation instance
+ */
+ public SourceSet jdkVersion(String jdkVersion) {
+ jdkVersion_ = jdkVersion;
+ return this;
+ }
+
+ /**
+ * Sets the version of JDK to use for linking to JDK Javadocs.
+ *
+ * The JDK version to use when generating external documentation links for Java types.
+ *
+ * For example, if you use {@link java.util.UUID} in some public declaration signature, and this option is set to 8,
+ * Dokka generates an external documentation link to JDK 8 Javadocs for it.
+ *
+ * @param jdkVersion the JDK version
+ * @return this operation instance
+ */
+ public SourceSet jdkVersion(int jdkVersion) {
+ jdkVersion_ = String.valueOf(jdkVersion);
+ return this;
+ }
+
+ /**
+ * Sets the language version used for setting up analysis and samples.
+ *
+ * @param languageVersion the language version
+ * @return this operation instance
+ */
+ public SourceSet languageVersion(String languageVersion) {
+ languageVersion_ = languageVersion;
+ return this;
+ }
+
+ /**
+ * Sets the language version used for setting up analysis and samples.
+ *
+ * @param languageVersion the language version
+ * @return this operation instance
+ */
+ public SourceSet languageVersion(int languageVersion) {
+ languageVersion_ = String.valueOf(languageVersion);
+ return this;
+ }
+
+ /**
+ * Sets whether to generate links to JDK Javadocs.
+ *
+ * Whether to generate external documentation links to JDK's Javadocs.
+ *
+ * The version of JDK Javadocs is determined by the {@link #jdkVersion jdkVersion} option.
+ *
+ * Note: Links are generated when noJdkLink is set to false.
+ *
+ * @param noJdkLink {@code true} or {@code false}
+ * @return this operation instance
+ */
+ public SourceSet noJdkLink(Boolean noJdkLink) {
+ noJdkLink_ = noJdkLink;
+ return this;
+ }
+
+ /**
+ * Sets whether to create pages for empty packages.
+ *
+ * Whether to skip packages that contain no visible declarations after various filters have been applied.
+ *
+ * @param noSkipEmptyPackages {@code true} or {@code false}
+ * @return this operation instance
+ */
+ public SourceSet noSkipEmptyPackages(boolean noSkipEmptyPackages) {
+ noSkipEmptyPackages_ = noSkipEmptyPackages;
+ return this;
+ }
+
+ /**
+ * Sets whether to generate links to Standard library.
+ *
+ * Whether to generate external documentation links that lead to the API reference documentation of Kotlin's
+ * standard library.
+ *
+ * Note: Links are generated when noStdLibLink is set to {@code false}.
+ *
+ * @param noStdlibLink {@code true} or {@code false}
+ * @return this operation instance
+ */
+ public SourceSet noStdlibLink(Boolean noStdlibLink) {
+ noStdlibLink_ = noStdlibLink;
+ return this;
+ }
+
+ /**
+ * Set the list of package source set configuration.
+ *
+ * A set of parameters specific to matched packages within this source set.
+ *
+ * Using format:
+ *
+ * - matchingRegexp
+ * - -deprecated
+ * - -privateApi
+ * - +warnUndocumented
+ * - +suppress
+ * - +visibility:PUBLIC
+ * - ...
+ *
+ *
+ * @param perPackageOptions the list of per package options
+ * @return this operation instance
+ */
+ public SourceSet perPackageOptions(Collection perPackageOptions) {
+ perPackageOptions_.addAll(perPackageOptions);
+ return this;
+ }
+
+ /**
+ * Set the list of package source set configuration.
+ *
+ * A set of parameters specific to matched packages within this source set.
+ *
+ * Using format:
+ *
+ * - matchingRegexp
+ * - -deprecated
+ * - -privateApi
+ * - +warnUndocumented
+ * - +suppress
+ * - +visibility:PUBLIC
+ * - ...
+ *
+ *
+ * @param perPackageOptions the list of per package options
+ * @return this operation instance
+ */
+ public SourceSet perPackageOptions(String... perPackageOptions) {
+ Collections.addAll(perPackageOptions_, perPackageOptions);
+ return this;
+ }
+
+ /**
+ * Sets whether to report undocumented declarations.
+ *
+ * Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs after they
+ * have been filtered by documentedVisibilities and other filters.
+ *
+ * This setting works well with {@link DokkaOperation#failOnWarning}.
+ *
+ * This can be configured on per-package basis.
+ *
+ * @param reportUndocumented {@code true} or {@code false}
+ * @return this operation instance
+ */
+ public SourceSet reportUndocumented(Boolean reportUndocumented) {
+ reportUndocumented_ = reportUndocumented;
+ return this;
+ }
+
+ /**
+ * Set the list of directories or files that contain sample functions.
+ *
+ * A list of directories or files that contain sample functions which are referenced via the {@code @sample} KDoc
+ * tag.
+ *
+ * @param samples the list of samples
+ * @return this operation instance
+ */
+ public SourceSet samples(Collection samples) {
+ samples_.addAll(samples);
+ return this;
+ }
+
+ /**
+ * Set the list of directories or files that contain sample functions.
+ *
+ * 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(String... samples) {
+ Collections.addAll(samples_, samples);
+ return this;
+ }
+
+ /**
+ * Sets whether to skip deprecated declarations.
+ *
+ * Whether to document declarations annotated with {@code @Deprecated}.
+ *
+ * This can be configured on per-package basis.
+ *
+ * @param skipDeprecated {@code true} or {@code false}
+ * @return this operation instance
+ */
+ public SourceSet skipDeprecated(boolean skipDeprecated) {
+ skipDeprecated_ = skipDeprecated;
+ return this;
+ }
+
+ /**
+ * Sets the name of the source set. Default is {@code main}.
+ *
+ * @param sourceSetName the source set name.
+ * @return this operation instance
+ */
+ public SourceSet sourceSetName(String sourceSetName) {
+ sourceSetName_ = sourceSetName;
+ return this;
+ }
+
+ /**
+ * Sets the source code roots to be analyzed and documented.
+ *
+ * The source code roots to be analyzed and documented. Acceptable inputs are directories and individual
+ * {@code .kt} / {@code .java} files.
+ *
+ * @param src the list of source code roots
+ * @return this operation instance
+ */
+ public SourceSet src(Collection src) {
+ src_.addAll(src);
+ return this;
+ }
+
+ /**
+ * Sets the source code roots to be analyzed and documented.
+ *
+ * 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_, src);
+ 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(String srcPath, String remotePath, String lineSuffix) {
+ srcLinks_.put(srcPath, remotePath + lineSuffix);
+ return this;
+ }
+
+ /**
+ * Sets the paths to files to be suppressed.
+ *
+ * The files to be suppressed when generating documentation.
+ *
+ * @param suppressedFiles the list of suppressed files
+ * @return this operation instance
+ */
+ public SourceSet suppressedFiles(Collection suppressedFiles) {
+ suppressedFiles_.addAll(suppressedFiles);
+ return this;
+ }
+
+ /**
+ * Sets the paths to files to be suppressed.
+ *
+ * The files to be suppressed when generating documentation.
+ *
+ * @param suppressedFiles one or moe suppressed files
+ * @return this operation instance
+ */
+ public SourceSet suppressedFiles(String... suppressedFiles) {
+ suppressedFiles_.addAll(Arrays.asList(suppressedFiles));
+ return this;
+ }
+}
diff --git a/src/test/java/rife/bld/extension/CompileKotlinOperationTest.java b/src/test/java/rife/bld/extension/CompileKotlinOperationTest.java
index 51205be..f64e6d3 100644
--- a/src/test/java/rife/bld/extension/CompileKotlinOperationTest.java
+++ b/src/test/java/rife/bld/extension/CompileKotlinOperationTest.java
@@ -18,17 +18,14 @@ package rife.bld.extension;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
-import rife.bld.Project;
import rife.bld.blueprints.BaseProjectBlueprint;
-import rife.bld.extension.kotlin.CompileOptions;
-import rife.bld.extension.kotlin.CompilerPlugin;
import rife.tools.FileUtils;
import java.io.File;
+import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
-import java.util.Arrays;
import java.util.List;
import java.util.Objects;
import java.util.logging.ConsoleHandler;
@@ -50,49 +47,7 @@ class CompileKotlinOperationTest {
}
@Test
- void testCollections() {
- var op = new CompileKotlinOperation()
- .fromProject(new Project())
- .compileMainClasspath("path1", "path2")
- .compileOptions(new CompileOptions().jdkRelease("17").verbose(true))
- .mainSourceDirectories("dir1", "dir2")
- .mainSourceDirectories(List.of(new File("dir3"), new File("dir4")))
- .mainSourceFiles("file1", "file2")
- .mainSourceFiles(List.of(new File("file3"), new File("file4")))
- .mainSourceFiles(new File("file5"), new File("file6"))
- .testSourceDirectories("tdir1", "tdir2")
- .testSourceDirectories(List.of(new File("tdir3"), new File("tdir4")))
- .testSourceFiles("tfile1", "tfile2")
- .testSourceFiles(List.of(new File("tfile3"), new File("tfile4")))
- .testSourceFiles(new File("tfile5"), new File("tfile6"))
- .plugins("plugin1", "plugin2")
- .plugins(CompilerPlugin.KOTLIN_SERIALIZATION, CompilerPlugin.ASSIGNMENT)
- .plugins(new File("lib/compile"), CompilerPlugin.LOMBOK, CompilerPlugin.POWER_ASSERT)
- .plugins(List.of("plugin3", "plugin4"))
- .plugins(Arrays.stream(Objects.requireNonNull(new File("lib/compile").listFiles())).toList(),
- CompilerPlugin.ALL_OPEN, CompilerPlugin.SAM_WITH_RECEIVER);
-
- assertThat(op.compileMainClasspath()).as("compileMainClassPath")
- .containsAll(List.of("path1", "path2"));
- assertThat(op.compileOptions().hasRelease()).as("hasRelease").isTrue();
- assertThat(op.compileOptions().isVerbose()).as("isVerbose").isTrue();
- assertThat(op.mainSourceDirectories()).as("mainSourceDirectories").containsExactly(
- Path.of("src", "main", "kotlin").toFile().getAbsoluteFile(), new File("dir1"),
- new File("dir2"), new File("dir3"), new File("dir4"));
- assertThat(op.testSourceDirectories()).as("testSourceDirectories").containsOnly(
- Path.of("src", "test", "kotlin").toFile().getAbsoluteFile(), new File("tdir1"),
- new File("tdir2"), new File("tdir3"), new File("tdir4"));
- assertThat(op.mainSourceFiles()).as("mainSourceFiles").containsOnly(
- new File("file1"), new File("file2"), new File("file3"),
- new File("file4"), new File("file5"), new File("file6"));
- assertThat(op.testSourceFiles()).as("testSourceFiles").containsOnly(
- new File("tfile1"), new File("tfile2"), new File("tfile3"),
- new File("tfile4"), new File("tfile5"), new File("tfile6"));
- assertThat(op.plugins()).hasSize(10);
- }
-
- @Test
- void testExecute() throws Exception {
+ void testExecute() throws IOException {
var tmpDir = Files.createTempDirectory("bld-kotlin").toFile();
try {
diff --git a/src/test/java/rife/bld/extension/kotlin/CompileOptionsTest.java b/src/test/java/rife/bld/extension/CompileKotlinOptionsTest.java
similarity index 56%
rename from src/test/java/rife/bld/extension/kotlin/CompileOptionsTest.java
rename to src/test/java/rife/bld/extension/CompileKotlinOptionsTest.java
index 25df90b..5c075fb 100644
--- a/src/test/java/rife/bld/extension/kotlin/CompileOptionsTest.java
+++ b/src/test/java/rife/bld/extension/CompileKotlinOptionsTest.java
@@ -14,7 +14,7 @@
* limitations under the License.
*/
-package rife.bld.extension.kotlin;
+package rife.bld.extension;
import org.junit.jupiter.api.Test;
@@ -23,39 +23,61 @@ import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.ArrayList;
-import java.util.Arrays;
import java.util.List;
-import java.util.stream.Collectors;
import java.util.stream.IntStream;
import static org.assertj.core.api.Assertions.assertThat;
@SuppressWarnings("PMD.AvoidDuplicateLiterals")
-class CompileOptionsTest {
- /**
- * Returns the local path of the given file names.
- *
- * @param fileNames The file names
- * @return the local path
- */
- private String localPath(String... fileNames) {
- return Arrays.stream(fileNames).map(it -> new File(it).getAbsolutePath())
- .collect(Collectors.joining(File.pathSeparator));
+class CompileKotlinOptionsTest {
+ @Test
+ void argsCollectionTest() {
+ var args = new CompileKotlinOptions()
+ .advancedOptions(List.of("Xoption1", "Xoption2"))
+ .argFile(List.of("arg1.txt", "arg2.txt"))
+ .classpath(List.of("path1", "path2"))
+ .jvmOptions(List.of("option1", "option2"))
+ .noStdLib(false)
+ .optIn(List.of("opt1", "opt2"))
+ .options(List.of("-foo", "-bar"))
+ .scriptTemplates(List.of("temp1", "temp2"))
+ .args();
+ var matches = List.of(
+ "@arg1.txt", "@arg2.txt",
+ "-classpath", "path1:path2",
+ "-Joption1", "-Joption2",
+ "-opt-in", "opt1",
+ "-opt-in", "opt2",
+ "-foo", "-bar",
+ "-script-templates",
+ "temp1,temp2",
+ "-XXoption1", "-XXoption2");
+
+ for (var arg : args) {
+ var found = false;
+ for (var match : matches) {
+ if (match.equals(arg)) {
+ found = true;
+ break;
+ }
+ }
+ assertThat(found).as(arg).isTrue();
+ }
}
+
@Test
- @SuppressWarnings("PMD.JUnitTestsShouldIncludeAssert")
- void testArgs() {
- var options = new CompileOptions()
+ void argsTest() {
+ var options = new CompileKotlinOptions()
.apiVersion("11")
- .argFile(new File("file.txt"), new File("file2.txt"))
- .classpath(new File("path1"), new File("path2"))
+ .argFile("file.txt", "file2.txt")
+ .classpath("path1", "path2")
.javaParameters(true)
.jvmTarget("11")
.includeRuntime(true)
- .jdkHome(new File("path"))
+ .jdkHome("path")
.jdkRelease("11")
- .kotlinHome(new File("path"))
+ .kotlinHome("path")
.languageVersion("1.0")
.moduleName("module")
.noJdk(true)
@@ -72,14 +94,14 @@ class CompileOptionsTest {
var matches = List.of(
"-api-version", "11",
- "@" + localPath("file.txt"), "@" + localPath("file2.txt"),
- "-classpath", localPath("path1", "path2"),
+ "@file.txt", "@file2.txt",
+ "-classpath", "path1" + File.pathSeparator + "path2",
"-java-parameters",
"-jvm-target", "11",
"-include-runtime",
- "-jdk-home", localPath("path"),
+ "-jdk-home", "path",
"-Xjdk-release=11",
- "-kotlin-home", localPath("path"),
+ "-kotlin-home", "path",
"-language-version", "1.0",
"-module-name", "module",
"-no-jdk",
@@ -89,7 +111,7 @@ class CompileOptionsTest {
"-opt-in", "opt2",
"-foo",
"-bar",
- "-d", localPath("path"),
+ "-d", "path",
"-P", "plugin:id:name:value",
"-progressive",
"-script-templates", "name,name2",
@@ -101,86 +123,18 @@ class CompileOptionsTest {
args.add(options.apiVersion(11).jvmTarget(11).args());
for (var a : args) {
+ assertThat(a).hasSize(matches.size());
IntStream.range(0, a.size()).forEach(i -> assertThat(a.get(i)).isEqualTo(matches.get(i)));
}
}
@Test
- void testArgsCollections() {
- var advanceOptions = List.of("Xoption1", "Xoption2");
- var argFile = List.of(new File("arg1.txt"), new File("arg2.txt"));
- var classpath = List.of(new File("path1"), new File("path2"));
- var jvmOptions = List.of("option1", "option2");
- var optIn = List.of("opt1", "opt2");
- var options = List.of("-foo", "-bar");
- var plugin = List.of("id:name:value", "id2:name2:value2");
- var scriptTemplates = List.of("temp1", "temp2");
-
- var op = new CompileOptions()
- .advancedOptions(advanceOptions)
- .argFile(argFile)
- .classpath(classpath)
- .jvmOptions(jvmOptions)
- .noStdLib(false)
- .optIn(optIn)
- .options(options)
- .scriptTemplates(scriptTemplates);
-
- plugin.forEach(it -> {
- var p = it.split(":");
- op.plugin(p[0], p[1], p[2]);
- });
-
- assertThat(op.advancedOptions()).as("advancedOptions")
- .hasSize(advanceOptions.size()).containsAll(advanceOptions);
- assertThat(op.argFile()).as("argFile")
- .hasSize(argFile.size()).containsAll(argFile);
- assertThat(op.classpath()).as("classpath")
- .hasSize(classpath.size()).containsAll(classpath);
- assertThat(op.jvmOptions()).as("jvmOptions")
- .hasSize(jvmOptions.size()).containsAll(jvmOptions);
- assertThat(op.optIn()).as("optIn")
- .hasSize(optIn.size()).containsAll(optIn);
- assertThat(op.options()).as("options")
- .hasSize(options.size()).containsAll(options);
- assertThat(op.plugin()).as("plugin")
- .hasSize(plugin.size()).containsAll(plugin);
- assertThat(op.scriptTemplates()).as("scriptTemplates")
- .hasSize(scriptTemplates.size()).containsAll(scriptTemplates);
-
- var matches = List.of(
- '@' + localPath("arg1.txt"), '@' + localPath("arg2.txt"),
- "-classpath", localPath("path1", "path2"),
- "-Joption1", "-Joption2",
- "-opt-in", "opt1",
- "-opt-in", "opt2",
- "-foo", "-bar",
- "-script-templates",
- "temp1,temp2",
- "-XXoption1", "-XXoption2",
- "-P", "plugin:id:name:value",
- "-P", "plugin:id2:name2:value2");
-
- var args = op.args();
- for (var arg : args) {
- var found = false;
- for (var match : matches) {
- if (match.equals(arg)) {
- found = true;
- break;
- }
- }
- assertThat(found).as(arg).isTrue();
- }
- }
-
- @Test
- void testCheckAllParams() throws IOException {
+ void checkAllParamsTest() throws IOException {
var args = Files.readAllLines(Paths.get("src", "test", "resources", "kotlinc-args.txt"));
assertThat(args).isNotEmpty();
- var params = new CompileOptions()
+ var params = new CompileKotlinOptions()
.advancedOptions("Xoption")
.argFile("file")
.classpath("classpath")
@@ -198,7 +152,7 @@ class CompileOptionsTest {
.noWarn(true)
.optIn("annotation")
.options("option")
- .path(new File("path"))
+ .path("path")
.plugin("id", "option", "value")
.progressive(true)
.scriptTemplates("template")
diff --git a/src/test/java/rife/bld/extension/dokka/DokkaOperationTest.java b/src/test/java/rife/bld/extension/dokka/DokkaOperationTest.java
new file mode 100644
index 0000000..0e089ee
--- /dev/null
+++ b/src/test/java/rife/bld/extension/dokka/DokkaOperationTest.java
@@ -0,0 +1,123 @@
+/*
+ * Copyright 2023-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package rife.bld.extension.dokka;
+
+import org.junit.jupiter.api.Test;
+import rife.bld.blueprints.BaseProjectBlueprint;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.IntStream;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class DokkaOperationTest {
+ @Test
+ @SuppressWarnings({"ExtractMethodRecommender", "PMD.AvoidDuplicateLiterals"})
+ void executeConstructProcessCommandListTest() throws IOException {
+ var args = Files.readAllLines(Paths.get("src", "test", "resources", "dokka-args.txt"));
+
+ assertThat(args).isNotEmpty();
+
+ var examples = new File("examples");
+ var jsonConf = new File("config.json");
+ var params = new DokkaOperation()
+ .delayTemplateSubstitution(true)
+ .failOnWarning(true)
+ .fromProject(new BaseProjectBlueprint(examples, "com.example", "Example"))
+ .globalLinks("s", "link")
+ .globalLinks(Map.of("s2", "link2"))
+ .globalPackageOptions("option1", "option2")
+ .globalPackageOptions(List.of("option3", "option4"))
+ .globalSrcLink("link1", "link2")
+ .globalSrcLink(List.of("link3", "link4"))
+ .includes("file1", "file2")
+ .includes(List.of("file3", "file4"))
+ .json(jsonConf)
+ .loggingLevel(LoggingLevel.DEBUG)
+ .moduleName("name")
+ .moduleVersion("1.0")
+ .noSuppressObviousFunctions(true)
+ .offlineMode(true)
+ .outputDir(new File(examples, "build"))
+ .outputFormat(OutputFormat.JAVADOC)
+ .pluginConfigurations("name", "{\"json\"}")
+ .pluginConfigurations(Map.of("{\"name2\"}", "json2", "name3}", "{json3"))
+ .pluginsClasspath("path1", "path2")
+ .pluginsClasspath(List.of("path3", "path4"))
+ .sourceSet(new SourceSet().classpath(
+ List.of(
+ new File("examples/foo.jar"),
+ new File("examples/bar.jar")
+ )))
+ .suppressInheritedMembers(true)
+ .executeConstructProcessCommandList();
+
+ for (var p : args) {
+ var found = false;
+ for (var a : params) {
+ if (a.startsWith(p)) {
+ found = true;
+ break;
+ }
+ }
+ assertThat(found).as(p + " not found.").isTrue();
+ }
+
+ var path = examples.getAbsolutePath();
+ var dokkaJar = "1.9.20.jar";
+ var matches = List.of("java",
+ "-jar", path + "/lib/bld/dokka-cli-" + dokkaJar,
+ "-pluginsClasspath", path + "/lib/bld/dokka-base-" + dokkaJar + ';' +
+ path + "/lib/bld/analysis-kotlin-descriptors-" + dokkaJar + ';' +
+ path + "/lib/bld/javadoc-plugin-" + dokkaJar + ';' +
+ path + "/lib/bld/korte-jvm-4.0.10.jar;" +
+ path + "/lib/bld/kotlin-as-java-plugin-" + dokkaJar + ";path1;path2;path3;path4",
+ "-sourceSet", "-src " + path + "/src/main/kotlin" + " -classpath " + path + "/foo.jar;" + path + "/bar.jar",
+ "-outputDir", path + "/build",
+ "-delayTemplateSubstitution",
+ "-failOnWarning",
+ "-globalLinks", "s^link^^s2^link2",
+ "-globalPackageOptions", "option1;option2;option3;option4",
+ "-globalSrcLinks_", "link1;link2;link3;link4",
+ "-includes", "file1;file2;file3;file4",
+ "-loggingLevel", "debug",
+ "-moduleName", "name",
+ "-moduleVersion", "1.0",
+ "-noSuppressObviousFunctions",
+ "-offlineMode",
+ "-pluginsConfiguration", "{\\\"name2\\\"}={json2}^^{name}={\\\"json\\\"}^^{name3}}={{json3}",
+ "-suppressInheritedMembers",
+ jsonConf.getAbsolutePath());
+
+ assertThat(params).hasSize(matches.size());
+
+ IntStream.range(0, params.size()).forEach(i -> {
+ if (params.get(i).contains(".jar;")) {
+ var jars = params.get(i).split(";");
+ Arrays.stream(jars).forEach(jar -> assertThat(matches.get(i)).as(matches.get(i)).contains(jar));
+ } else {
+ assertThat(params.get(i)).as(params.get(i)).isEqualTo(matches.get(i));
+ }
+ });
+ }
+}
diff --git a/src/test/java/rife/bld/extension/dokka/SourceSetTest.java b/src/test/java/rife/bld/extension/dokka/SourceSetTest.java
new file mode 100644
index 0000000..b503335
--- /dev/null
+++ b/src/test/java/rife/bld/extension/dokka/SourceSetTest.java
@@ -0,0 +1,132 @@
+/*
+ * Copyright 2023-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package rife.bld.extension.dokka;
+
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.IntStream;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class SourceSetTest {
+ @Test
+ void sourceSetCollectionsTest() {
+ var args = new SourceSet()
+ .classpath(List.of("path1", "path2"))
+ .dependentSourceSets(Map.of("set1", "set2", "set3", "set4"))
+ .externalDocumentationLinks(Map.of("link1", "link2", "link3", "link4"))
+ .perPackageOptions(List.of("option1", "option2"))
+ .samples(List.of("samples1", "samples1"))
+ .suppressedFiles(List.of("sup1", "sup2"))
+ .args();
+
+ var matches = List.of(
+ "-classpath", "path1;path2",
+ "-dependentSourceSets", "set1/set2;set3/set4",
+ "-externalDocumentationLinks", "link3^link4^^link1^link2",
+ "-perPackageOptions", "option1;option2",
+ "-samples", "samples1;samples1",
+ "-suppressedFiles", "sup1;sup2"
+ );
+
+ assertThat(args).hasSize(matches.size());
+
+ IntStream.range(0, args.size()).forEach(i -> assertThat(args.get(i)).isEqualTo(matches.get(i)));
+ }
+
+ @Test
+ @SuppressWarnings("PMD.AvoidDuplicateLiterals")
+ void sourceSetTest() throws IOException {
+ var args = Files.readAllLines(Paths.get("src", "test", "resources", "dokka-sourceset-args.txt"));
+
+ assertThat(args).isNotEmpty();
+
+ var sourceSet = new SourceSet()
+ .analysisPlatform(AnalysisPlatform.JVM)
+ .apiVersion("1.0")
+ .classpath("classpath1", "classpath2")
+ .dependentSourceSets("moduleName", "sourceSetName")
+ .displayName("name")
+ .documentedVisibilities(DocumentedVisibility.PACKAGE, DocumentedVisibility.PRIVATE)
+ .externalDocumentationLinks("url1", "packageListUrl1")
+ .externalDocumentationLinks("url2", "packageListUrl2")
+ .includes("includes1", "includes2")
+ .jdkVersion(18)
+ .languageVersion("2.0")
+ .noJdkLink(true)
+ .noSkipEmptyPackages(true)
+ .noStdlibLink(true)
+ .perPackageOptions("options1", "options2")
+ .reportUndocumented(true)
+ .samples("samples1", "sample2")
+ .skipDeprecated(true)
+ .sourceSetName("setName")
+ .src("src1", "src2")
+ .srcLink("path1", "remote1", "#suffix1")
+ .srcLink("path2", "remote2", "#suffix2")
+ .suppressedFiles("sup1", "sup2");
+
+ var params = sourceSet.args();
+
+ for (var p : args) {
+ var found = false;
+ for (var a : params) {
+ if (a.startsWith(p)) {
+ found = true;
+ break;
+ }
+ }
+ assertThat(found).as(p + " not found.").isTrue();
+ }
+
+ var matches = List.of(
+ "-analysisPlatform", "jvm",
+ "-apiVersion", "1.0",
+ "-classpath", "classpath1;classpath2",
+ "-dependentSourceSets", "moduleName/sourceSetName",
+ "-displayName", "name",
+ "-documentedVisibilities", "package;private",
+ "-externalDocumentationLinks", "url1^packageListUrl1^^url2^packageListUrl2",
+ "-jdkVersion", "18",
+ "-includes", "includes1;includes2",
+ "-languageVersion", "2.0",
+ "-noJdkLink", "true",
+ "-noSkipEmptyPackages", "true",
+ "-noStdlibLink", "true",
+ "-reportUndocumented", "true",
+ "-perPackageOptions", "options1;options2",
+ "-samples", "samples1;sample2",
+ "-skipDeprecated", "true",
+ "-src", "src1;src2",
+ "-srcLink", "path1=remote1#suffix1;path2=remote2#suffix2",
+ "-sourceSetName", "setName",
+ "-suppressedFiles", "sup1;sup2");
+
+ assertThat(params).hasSize(matches.size());
+
+ IntStream.range(0, params.size()).forEach(i -> assertThat(params.get(i)).isEqualTo(matches.get(i)));
+
+ sourceSet.classpath(List.of("classpath1", "classpath2"));
+
+ IntStream.range(0, params.size()).forEach(i -> assertThat(params.get(i)).isEqualTo(matches.get(i)));
+ }
+}
diff --git a/src/test/resources/dokka-args.txt b/src/test/resources/dokka-args.txt
new file mode 100644
index 0000000..4c9f29c
--- /dev/null
+++ b/src/test/resources/dokka-args.txt
@@ -0,0 +1,16 @@
+-delayTemplateSubstitution
+-failOnWarning
+-globalLinks
+-globalPackageOptions
+-globalSrcLink
+-includes
+-loggingLevel
+-moduleName
+-moduleVersion
+-noSuppressObviousFunctions
+-offlineMode
+-outputDir
+-pluginsClasspath
+-pluginsConfiguration
+-sourceSet
+-suppressInheritedMembers
diff --git a/src/test/resources/dokka-sourceset-args.txt b/src/test/resources/dokka-sourceset-args.txt
new file mode 100644
index 0000000..0699eb7
--- /dev/null
+++ b/src/test/resources/dokka-sourceset-args.txt
@@ -0,0 +1,21 @@
+-analysisPlatform
+-apiVersion
+-classpath
+-dependentSourceSets
+-displayName
+-documentedVisibilities
+-externalDocumentationLinks
+-includes
+-jdkVersion
+-languageVersion
+-noJdkLink
+-noSkipEmptyPackages
+-noStdlibLink
+-perPackageOptions
+-reportUndocumented
+-samples
+-skipDeprecated
+-sourceSetName
+-src
+-srcLink
+-suppressedFiles