diff --git a/examples/lib/bld/bld-wrapper.properties b/examples/lib/bld/bld-wrapper.properties index e1bfbba..6528a5e 100644 --- a/examples/lib/bld/bld-wrapper.properties +++ b/examples/lib/bld/bld-wrapper.properties @@ -1,7 +1,7 @@ bld.downloadExtensionJavadoc=false bld.downloadExtensionSources=true bld.extensions=com.uwyn.rife2:bld-kotlin:0.9.0-SNAPSHOT -bld.repositories=MAVEN_LOCAL,RIFE2_SNAPSHOTS,MAVEN_CENTRAL,RIFE2_RELEASES +bld.repositories=MAVEN_LOCAL,MAVEN_CENTRAL bld.downloadLocation= bld.sourceDirectories= bld.version=1.7.5 diff --git a/examples/src/bld/java/com/example/ExampleBuild.java b/examples/src/bld/java/com/example/ExampleBuild.java index 5e3f929..52cbfbe 100644 --- a/examples/src/bld/java/com/example/ExampleBuild.java +++ b/examples/src/bld/java/com/example/ExampleBuild.java @@ -3,6 +3,8 @@ package com.example; import rife.bld.BaseProject; import rife.bld.BuildCommand; import rife.bld.extension.CompileKotlinOperation; +import rife.bld.extension.dokka.DokkaOperation; +import rife.bld.operations.exceptions.ExitStatusException; import java.io.IOException; import java.util.List; @@ -50,4 +52,11 @@ public class ExampleBuild extends BaseProject { .compileOptions("-verbose") .execute(); } + + @BuildCommand(summary = "Generates Javadoc for the project") + public void javadoc() throws ExitStatusException, IOException, InterruptedException { + new DokkaOperation() + .fromProject(this) + .execute(); + } } \ No newline at end of file diff --git a/src/bld/java/rife/bld/extension/CompileKotlinOperationBuild.java b/src/bld/java/rife/bld/extension/CompileKotlinOperationBuild.java index 16a7c25..d70aed3 100644 --- a/src/bld/java/rife/bld/extension/CompileKotlinOperationBuild.java +++ b/src/bld/java/rife/bld/extension/CompileKotlinOperationBuild.java @@ -40,8 +40,13 @@ public class CompileKotlinOperationBuild extends Project { autoDownloadPurge = true; repositories = List.of(MAVEN_LOCAL, MAVEN_CENTRAL, RIFE2_RELEASES); + var dokka = version(1, 9, 10); scope(compile) .include(dependency("org.jetbrains.kotlin", "kotlin-compiler", version(1, 9, 20))) + .include(dependency("org.jetbrains.dokka", "dokka-cli", dokka)) + .include(dependency("org.jetbrains.dokka", "dokka-base", dokka)) + .include(dependency("org.jetbrains.dokka", "analysis-kotlin-descriptors", dokka)) + .include(dependency("org.jetbrains.dokka", "javadoc-plugin", dokka)) .include(dependency("com.uwyn.rife2", "bld", version(1, 7, 5))); scope(test) .include(dependency("org.junit.jupiter", "junit-jupiter", version(5, 10, 0))) diff --git a/src/main/java/rife/bld/extension/CompileKotlinOperation.java b/src/main/java/rife/bld/extension/CompileKotlinOperation.java index 8d17f11..2618da4 100644 --- a/src/main/java/rife/bld/extension/CompileKotlinOperation.java +++ b/src/main/java/rife/bld/extension/CompileKotlinOperation.java @@ -105,7 +105,7 @@ public class CompileKotlinOperation extends AbstractOperationErik C. Thauvin + * @since 1.0 + */ +public enum AnalysisPlatform { + JVM, JS, NATIVE, COMMON, ANDROID +} \ No newline at end of file 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..a95b385 --- /dev/null +++ b/src/main/java/rife/bld/extension/dokka/DocumentedVisibility.java @@ -0,0 +1,27 @@ +/* + * Copyright 2023 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..be8145e --- /dev/null +++ b/src/main/java/rife/bld/extension/dokka/DokkaOperation.java @@ -0,0 +1,408 @@ +/* + * Copyright 2023 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.operations.AbstractProcessOperation; + +import java.io.File; +import java.util.*; +import java.util.concurrent.ConcurrentHashMap; +import java.util.logging.Level; +import java.util.logging.Logger; + +/** + * Builds Javadocs using Dokka. + * + * @author Erik C. Thauvin + * @since 1.0 + */ +public class DokkaOperation extends AbstractProcessOperation { + 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 Map pluginConfiguration_ = new ConcurrentHashMap<>(); + private final Collection pluginsClasspath_ = new ArrayList<>(); + private Boolean delayTemplateSubstitution_; + private Boolean failOnWarning_; + 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_; + + /** + * 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} 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 = 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) { + outputDir_ = new File("./dokka"); + } + args.add("-outputDir"); + args.add(outputDir_.getAbsolutePath()); + + if (LOGGER.isLoggable(Level.FINE)) { + LOGGER.fine(String.join(" ", args)); + } + + return args; + } + + /** + * Configures the operation from a {@link BaseProject}. + * + * @param project the project to configure the operation from + */ + @Override + public DokkaOperation fromProject(BaseProject project) { + project_ = project; + var plugins = getJarList( + project.libBldDirectory(), + "^.*(dokka-base|analysis-kotlin-descriptors|javadoc-plugin|kotlin-as-java-plugin|korte-jvm).*\\.jar$"); + pluginsClasspath_.addAll(plugins); + sourceSet_ = new SourceSet().src(new File(project.srcMainDirectory(), "kotlin")); + outputDir_ = new File(project.buildDirectory(), "javadoc"); + return this; + } + + /** + * Sets whether to fail documentation generation if Dokka has emitted a warning or an error. + * + * @param failOnWarning the fail on warning ;toggle + * @return this operation instance + */ + public DokkaOperation failOnWarning(Boolean failOnWarning) { + failOnWarning_ = failOnWarning; + return this; + } + + private List getJarList(File directory, String regex) { + var jars = new ArrayList(); + + if (directory.isDirectory()) { + var files = directory.listFiles(); + if (files != null) { + for (var f : files) { + if (!f.getName().contains("-sources")) { + if (f.getName().matches(regex)) { + jars.add(f.getAbsolutePath()); + } + } + } + } + } + + return jars; + } + + /** + * 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...) + */ + public DokkaOperation globalLinks(Map globalLinks) { + globalLinks_.putAll(globalLinks); + return this; + } + + /** + * Sets the global list of package configurations in format: + *
    + *
  • matchingRegexp
  • + *
  • -deprecated
  • + *
  • -privateApi
  • + *
  • +warnUndocumented
  • + *
  • +suppress
  • + *
  • ...
  • + *
+ * + * @param options ome pr more package configurations + * @return this operation instance + */ + public DokkaOperation globalPackageOptions(String... options) { + globalPackageOptions_.addAll(Arrays.asList(options)); + return this; + } + + /** + * Sets the global list of package configurations in format: + *
    + *
  • matchingRegexp
  • + *
  • -deprecated
  • + *
  • -privateApi
  • + *
  • +warnUndocumented
  • + *
  • +suppress
  • + *
  • ...
  • + *
+ * + * @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) { + globalSrcLinks_.addAll(Arrays.asList(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. + * + * @param files one or more files + * @return this operation instance + */ + public DokkaOperation includes(File... files) { + includes_.addAll(Arrays.asList(files)); + return this; + } + + /** + * Sets the Markdown files that contain module and package documentation. + * + * @param files the list of files + * @return this operation instance + */ + public DokkaOperation includss(Collection files) { + includes_.addAll(files); + 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}. + * + * @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 {@code kotlin.Any} and + * {@link java.lang.Object java.lang.Object}. + * + * @param noSuppressObviousFunctions the suppress toggle + * @return this operation instance + */ + public DokkaOperation noSuppressObviousFunctions(Boolean noSuppressObviousFunctions) { + noSuppressObviousFunctions_ = noSuppressObviousFunctions; + return this; + } + + /** + * Sets whether to resolve remote files/links over network. + * + * @param offlineMode the offline mode + * @return this operation instance + */ + public DokkaOperation offlineMode(Boolean offlineMode) { + offlineMode_ = offlineMode; + return this; + } + + /** + * Sets the output directory path, {@code ./dokka} by default + * + * @param outputDir the output directory + * @return this operation instance + */ + public DokkaOperation outputDir(File outputDir) { + outputDir_ = outputDir; + 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 pluginClassPath(String... jars) { + pluginsClasspath_.addAll(Arrays.asList(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 pluginClassPath(Collection jars) { + pluginsClasspath_.addAll(jars); + 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 pluginConfiguration(String name, String jsonConfiguration) { + pluginConfiguration_.put(name, jsonConfiguration); + return this; + } + + /** + * Sets the configuration for Dokka plugins. + * + * @param pluginConfiguration the map of configurations + * @return this operation instance + * @see #pluginConfiguration(String, String) + */ + public DokkaOperation pluginConfiguration(Map pluginConfiguration) { + pluginConfiguration_.putAll(pluginConfiguration); + return this; + } + + /** + * Sets the configurations for a source set. + * + * @param sourceSet the source set configurations + * @return this operation instance + */ + private 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 the suppress toggle + * @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..a3f9210 --- /dev/null +++ b/src/main/java/rife/bld/extension/dokka/LoggingLevel.java @@ -0,0 +1,27 @@ +/* + * Copyright 2023 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/SourceSet.java b/src/main/java/rife/bld/extension/dokka/SourceSet.java new file mode 100644 index 0000000..ac9177c --- /dev/null +++ b/src/main/java/rife/bld/extension/dokka/SourceSet.java @@ -0,0 +1,409 @@ +/* + * Copyright 2023 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 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 int 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} + * + * @param analysisPlatform the analysis platfrom + * @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; + } + + /** + * Returns the formatted arguments. + * + * @return the arguments + */ + public List args() { + var args = new ArrayList(); + + // -src + if (!src_.isEmpty()) { + args.add("-src"); + src_.forEach(s -> args.add(s.getAbsolutePath() + ';')); + } + + return args; + } + + /** + * Sets classpath for analysis and interactive samples. + * + * @param classpath one or more classpath + * @return this operation instance + */ + public SourceSet classpath(File... classpath) { + classpath_.addAll(Arrays.asList(classpath)); + return this; + } + + /** + * Sets classpath for analysis and interactive samples. + * + * @param classpath the list of classpath + * @return this operation instance + */ + public SourceSet classpath(Collection classpath) { + classpath_.addAll(classpath); + 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. + * + * @param displayName the display name + * @return this operation instance + */ + public SourceSet displayName(String displayName) { + displayName_ = displayName; + return this; + } + + /** + * Sets visibilities to be documented. + * + * @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. + * + * @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. + * + * @param externalDocumentationLinks the map of external documentation links + * @return this operation instance + * @see #dependentSourceSets(String, String) + */ + public SourceSet externalDocumentationLinks(Map externalDocumentationLinks) { + externalDocumentationLinks_.putAll(externalDocumentationLinks); + return this; + } + + /** + * Sets the Markdown files that contain module and package documentation. + * + * @param files one or more files + * @return this operation instance + */ + public SourceSet includes(File... files) { + includes_.addAll(Arrays.asList(files)); + return this; + } + + /** + * Sets the Markdown files that contain module and package documentation. + * + * @param files the list of files + * @return this operation instance + */ + public SourceSet includss(Collection files) { + includes_.addAll(files); + return this; + } + + /** + * Sets the version of JDK to use for linking to JDK Javadocs. + * + * @param jdkVersion the JDK version + * @return this operation instance + */ + public SourceSet jdkVersion(int jdkVersion) { + jdkVersion_ = 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 whether to generate links to JDK Javadocs. + * + * @param noJdkLink the no JDK link toggle + * @return this operation instance + */ + public SourceSet noJdkLink(Boolean noJdkLink) { + noJdkLink_ = noJdkLink; + return this; + } + + /** + * Sets whether to create pages for empty packages. + * + * @param noSkipEmptyPackages the no skip empty packages toggle + * @return this operation instance + */ + public SourceSet noSkipEmptyPackages(boolean noSkipEmptyPackages) { + noSkipEmptyPackages_ = noSkipEmptyPackages; + return this; + } + + /** + * Sets whether to generate links to Standard library. + * + * @param noStdlibLink the no std lib link toggle + * @return this operation instance + */ + public SourceSet noStdlibLink(Boolean noStdlibLink) { + noStdlibLink_ = noStdlibLink; + return this; + } + + /** + * Set the list of package source set configuration in format: + *
    + *
  • + *
  • -deprecated
  • + *
  • -privateApi
  • + *
  • +warnUndocumented
  • + *
  • +suppress
  • + *
  • ...
  • + *
+ * + * @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 in format: + *
    + *
  • + *
  • -deprecated
  • + *
  • -privateApi
  • + *
  • +warnUndocumented
  • + *
  • +suppress
  • + *
  • ...
  • + *
+ * + * @param perPackageOptions one or more per package options + * @return this operation instance + */ + public SourceSet perPackageOptions(String... perPackageOptions) { + perPackageOptions_.addAll(List.of(perPackageOptions)); + return this; + } + + /** + * Sets Wwether to report undocumented declarations. + * + * @param reportUndocumented the report undocumented toggle + * @return this operation instance + */ + public SourceSet reportUndocumented(Boolean reportUndocumented) { + reportUndocumented_ = reportUndocumented; + return this; + } + + /** + * Set the list of directories or files that contain sample functions. + * + * @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. + * + * @param samples nne or more samples + * @return this operation instance + */ + public SourceSet samples(File... samples) { + samples_.addAll(List.of(samples)); + return this; + } + + /** + * Sets whether to skip deprecated declarations. + * + * @param skipDeprecated the skip deprecated toggle + * @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. + * + * @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. + * + * @param src pne ore moe source code roots + * @return this operation instance + */ + public SourceSet src(File... src) { + src_.addAll(List.of(src)); + return this; + } + + /** + * Sets the mpping 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 srcLinks(String srcPath, String remotePath, String lineSuffix) { + srcLinks_.put(srcPath, remotePath + '#' + lineSuffix); + return this; + } + + /** + * Sets the paths to files to be suppressed. + * + * @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. + * + * @param suppressedFiles one or moe suppressed files + * @return this operation instance + */ + public SourceSet suppressedFiles(File... suppressedFiles) { + suppressedFiles_.addAll(Arrays.asList(suppressedFiles)); + return this; + } +}