rife2/bld-kotlin
rife2/bld-kotlin
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Moved Dokka operation to its own extension

Browse source
This commit is contained in:
Erik C. Thauvin 2024-06-15 21:31:36 -07:00
parent 1623b902f9
commit 8d34f37af0
Signed by: erik
GPG key ID: 776702A6A2DA330E
19 changed files with 26 additions and 1828 deletions
Download patch file Download diff file Expand all files Collapse all files

27
src/main/java/rife/bld/extension/dokka/AnalysisPlatform.java
View file

@ -1,27 +0,0 @@
/*
* 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 <a href="https://erik.thauvin.net/">Erik C. Thauvin</a>
* @since 1.0
*/
public enum AnalysisPlatform {
JVM, JS, NATIVE, COMMON, ANDROID
}

27
src/main/java/rife/bld/extension/dokka/DocumentedVisibility.java
View file

@ -1,27 +0,0 @@
/*
* 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 <a href="https://erik.thauvin.net/">Erik C. Thauvin</a>
* @since 1.0
*/
public enum DocumentedVisibility {
PUBLIC, PRIVATE, PROTECTED, INTERNAL, PACKAGE
}

609
src/main/java/rife/bld/extension/dokka/DokkaOperation.java
View file

@ -1,609 +0,0 @@
/*
* 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 <a href="https://erik.thauvin.net/">Erik C. Thauvin</a>
* @since 1.0
*/
@SuppressWarnings("PMD.AvoidThrowingRawExceptionTypes")
public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
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<String, String> globalLinks_ = new ConcurrentHashMap<>();
private final Collection<String> globalPackageOptions_ = new ArrayList<>();
private final Collection<String> globalSrcLinks_ = new ArrayList<>();
private final Collection<String> includes_ = new ArrayList<>();
private final Collection<String> pluginsClasspath_ = new ArrayList<>();
private final Map<String, String> 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.
* <p>
* 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<String> executeConstructProcessCommandList() {
if (project_ == null) {
throw new IllegalArgumentException("A project must be specified.");
}
final List<String> 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<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 (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<String>();
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}.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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<String, String> globalLinks) {
globalLinks_.putAll(globalLinks);
return this;
}
/**
* Sets the global list of package configurations.
* <p>
* Using format:
* <ul>
* <li>matchingRegexp</li>
* <li>-deprecated</li>
* <li>-privateApi</li>
* <li>+warnUndocumented</li>
* <li>+suppress</li>
* <li>+visibility:PUBLIC</li>
* <li>...</li>
* </ul>
*
* @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.
* <p>
* Using format:
* <ul>
* <li>matchingRegexp</li>
* <li>-deprecated</li>
* <li>-privateApi</li>
* <li>+warnUndocumented</li>
* <li>+suppress</li>
* <li>+visibility:PUBLIC</li>
* <li>...</li>
* </ul>
*
* @param options the list of package configurations
* @return this operation instance
*/
public DokkaOperation globalPackageOptions(Collection<String> 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<String> links) {
globalSrcLinks_.addAll(links);
return this;
}
/**
* Sets the Markdown files that contain module and package documentation.
* <p>
* The contents of specified files are parsed and embedded into documentation as module and package descriptions.
* <p>
* This can be configured on per-package basis.
*
* @param files one or more files
* @return this operation instance
*/
public DokkaOperation includes(String... files) {
Collections.addAll(includes_, files);
return this;
}
/**
* Sets the Markdown files that contain module and package documentation.
* <p>
* The contents of specified files are parsed and embedded into documentation as module and package descriptions.
* <p>
* This can be configured on per-package basis.
*
* @param files the list of files
* @return this operation instance
*/
public DokkaOperation includes(Collection<String> 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}.
* <p>
* 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
* <a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/">kotlin.Any</a> and {@link java.lang.Object}.
* <p>
* A function is considered to be obvious if it is:
* <ul>
* <li>Inherited from <a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/">kotlin.Any</a>,
* <a href="https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-enum/">Kotlin.Enum</a>, {@link java.lang.Object}
* or {@link java.lang.Enum}, such as {@code equals}, {@code hashCode}, {@code toString}.
* <li>Synthetic (generated by the compiler) and does not have any documentation, such as
* {@code dataClass.componentN} or {@code dataClass.copy}.
* </ul>
*
* @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.
* <p>
* This includes package-lists used for generating external documentation links. For example, to make classes from
* the standard library clickable.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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<String, String> 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<String> jars) {
pluginsClasspath_.addAll(jars);
return this;
}
/**
* Clears the list of Dokka plugins.
*
* @param clear set to clear the list
* @return this operation instance
*/
public DokkaOperation pluginsClasspath(boolean clear) {
if (clear) {
pluginsClasspath_.clear();
}
return this;
}
/**
* Sets the configurations for a source set.
* <p>
* 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;
}
}

27
src/main/java/rife/bld/extension/dokka/LoggingLevel.java
View file

@ -1,27 +0,0 @@
/*
* 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 <a href="https://erik.thauvin.net/">Erik C. Thauvin</a>
* @since 1.0
*/
public enum LoggingLevel {
DEBUG, PROGRESS, INFO, WARN, ERROR
}

27
src/main/java/rife/bld/extension/dokka/OutputFormat.java
View file

@ -1,27 +0,0 @@
/*
* 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 <a href="https://erik.thauvin.net/">Erik C. Thauvin</a>
* @since 1.0
*/
public enum OutputFormat {
JAVADOC, JEKYLL, HTML, MARKDOWN
}

680
src/main/java/rife/bld/extension/dokka/SourceSet.java
View file

@ -1,680 +0,0 @@
/*
* 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 <a href="https://erik.thauvin.net/">Erik C. Thauvin</a>
* @since 1.0
*/
public class SourceSet {
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<String> includes_ = new ArrayList<>();
private final Collection<String> perPackageOptions_ = new ArrayList<>();
private final Collection<String> samples_ = new ArrayList<>();
private final Map<String, String> srcLinks_ = new ConcurrentHashMap<>();
private final Collection<String> src_ = new ArrayList<>();
private final Collection<String> suppressedFiles_ = new ArrayList<>();
private 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}
* <p>
* 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<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_ != 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<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;
}
/**
* Sets classpath for analysis and interactive samples.
* <p>
* This is useful if some types that come from dependencies are not resolved/picked up automatically.
* <p>
* 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.
* <p>
* This is useful if some types that come from dependencies are not resolved/picked up automatically.
* <p>
* This option accepts both {@code .jar} and {@code .klib} files.
*
* @param files the list of files
* @return this operation instance
*/
public SourceSet classpath(Collection<String> files) {
classpath_.addAll(files);
return this;
}
/**
* Sets classpath for analysis and interactive samples.
* <p>
* This is useful if some types that come from dependencies are not resolved/picked up automatically.
* <p>
* This option accepts both {@code .jar} and {@code .klib} files.
*
* @param files the list of files
* @return this operation instance
*/
public SourceSet classpath(List<File> 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<String, String> dependentSourceSets) {
dependentSourceSets_.putAll(dependentSourceSets);
return this;
}
/**
* Sets the display name of the source set, used both internally and externally.
* <p>
* 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}).
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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.
* <p>
* 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<String, String> externalDocumentationLinks) {
externalDocumentationLinks_.putAll(externalDocumentationLinks);
return this;
}
/**
* Sets the Markdown files that contain module and package documentation.
* <p>
* A list of Markdown files that contain module and package documentation.
* <p>
* The contents of the specified files are parsed and embedded into documentation as module and package
* descriptions.
*
* @param files one or more files
* @return this operation instance
*/
public SourceSet includes(String... files) {
Collections.addAll(includes_, files);
return this;
}
/**
* Sets the Markdown files that contain module and package documentation.
* <p>
* A list of Markdown files that contain module and package documentation.
* <p>
* The contents of the specified files are parsed and embedded into documentation as module and package
* descriptions.
*
* @param files the list of files
* @return this operation instance
*/
public SourceSet includes(Collection<String> files) {
includes_.addAll(files);
return this;
}
/**
* Sets the version of JDK to use for linking to JDK Javadocs.
* <p>
* The JDK version to use when generating external documentation links for Java types.
* <p>
* 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.
* <p>
* The JDK version to use when generating external documentation links for Java types.
* <p>
* 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.
* <p>
* Whether to generate external documentation links to JDK's Javadocs.
* <p>
* The version of JDK Javadocs is determined by the {@link #jdkVersion jdkVersion} option.
* <p>
* 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.
* <p>
* 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.
* <p>
* Whether to generate external documentation links that lead to the API reference documentation of Kotlin's
* standard library.
* <p>
* 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.
* <p>
* A set of parameters specific to matched packages within this source set.
* <p>
* Using format:
* <ul>
* <li>matchingRegexp</li>
* <li>-deprecated</li>
* <li>-privateApi</li>
* <li>+warnUndocumented</li>
* <li>+suppress</li>
* <li>+visibility:PUBLIC</li>
* <li>...</li>
* </ul>
*
* @param perPackageOptions the list of per package options
* @return this operation instance
*/
public SourceSet perPackageOptions(Collection<String> perPackageOptions) {
perPackageOptions_.addAll(perPackageOptions);
return this;
}
/**
* Set the list of package source set configuration.
* <p>
* A set of parameters specific to matched packages within this source set.
* <p>
* Using format:
* <ul>
* <li>matchingRegexp</li>
* <li>-deprecated</li>
* <li>-privateApi</li>
* <li>+warnUndocumented</li>
* <li>+suppress</li>
* <li>+visibility:PUBLIC</li>
* <li>...</li>
* </ul>
*
* @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.
* <p>
* Whether to emit warnings about visible undocumented declarations, that is declarations without KDocs after they
* have been filtered by documentedVisibilities and other filters.
* <p>
* This setting works well with {@link DokkaOperation#failOnWarning}.
* <p>
* 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.
* <p>
* 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<String> samples) {
samples_.addAll(samples);
return this;
}
/**
* Set the list of directories or files that contain sample functions.
* <p>
* A list of directories or files that contain sample functions which are referenced via the {@code @sample} KDoc
* tag.
*
* @param samples nne or more samples
* @return this operation instance
*/
public SourceSet samples(String... samples) {
Collections.addAll(samples_, samples);
return this;
}
/**
* Sets whether to skip deprecated declarations.
* <p>
* Whether to document declarations annotated with {@code @Deprecated}.
* <p>
* 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.
* <p>
* 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<String> src) {
src_.addAll(src);
return this;
}
/**
* Sets the source code roots to be analyzed and documented.
* <p>
* The source code roots to be analyzed and documented. Acceptable inputs are directories and individual
* {@code .kt} / {@code .java} files.
*
* @param src pne ore moe source code roots
* @return this operation instance
*/
public SourceSet src(String... src) {
Collections.addAll(src_, 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.
* <p>
* The files to be suppressed when generating documentation.
*
* @param suppressedFiles the list of suppressed files
* @return this operation instance
*/
public SourceSet suppressedFiles(Collection<String> suppressedFiles) {
suppressedFiles_.addAll(suppressedFiles);
return this;
}
/**
* Sets the paths to files to be suppressed.
* <p>
* The files to be suppressed when generating documentation.
*
* @param suppressedFiles one or moe suppressed files
* @return this operation instance
*/
public SourceSet suppressedFiles(String... suppressedFiles) {
suppressedFiles_.addAll(Arrays.asList(suppressedFiles));
return this;
}
}