Convert parameters from String to File whenever applicable
Some checks failed
bld-ci / build-bld-project (17) (push) Has been cancelled
bld-ci / build-bld-project (21) (push) Has been cancelled
bld-ci / build-bld-project (22) (push) Has been cancelled
javadocs-pages / deploy (push) Has been cancelled

This commit is contained in:
Erik C. Thauvin 2024-06-17 02:58:19 -07:00
parent 2d5a3068cf
commit af8e211feb
Signed by: erik
GPG key ID: 776702A6A2DA330E
7 changed files with 429 additions and 92 deletions

View file

@ -1,6 +1,6 @@
<component name="CopyrightManager"> <component name="CopyrightManager">
<copyright> <copyright>
<option name="notice" value="Copyright 2023-Copyright &amp;#36;today.yearamp;#36;today.year the original author or authors.&#10; &#10;Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);&#10;you may not use this file except in compliance with the License.&#10;You may obtain a copy of the License at&#10;&#10; https://www.apache.org/licenses/LICENSE-2.0&#10;&#10;Unless required by applicable law or agreed to in writing, software&#10;distributed under the License is distributed on an &quot;AS IS&quot; BASIS,&#10;WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.&#10;See the License for the specific language governing permissions and&#10;limitations under the License." /> <option name="notice" value="Copyright 2023-&amp;#36;today.year the original author or authors.&#10;&#10;Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);&#10;you may not use this file except in compliance with the License.&#10;You may obtain a copy of the License at&#10;&#10; https://www.apache.org/licenses/LICENSE-2.0&#10;&#10;Unless required by applicable law or agreed to in writing, software&#10;distributed under the License is distributed on an &quot;AS IS&quot; BASIS,&#10;WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.&#10;See the License for the specific language governing permissions and&#10;limitations under the License." />
<option name="myName" value="Apache License" /> <option name="myName" value="Apache License" />
</copyright> </copyright>
</component> </component>

17
.idea/misc.xml generated
View file

@ -1,7 +1,24 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<project version="4"> <project version="4">
<component name="EntryPointsManager"> <component name="EntryPointsManager">
<entry_points version="2.0">
<entry_point TYPE="field" FQNAME="rife.bld.extension.dokka.AnalysisPlatform ANDROID" />
<entry_point TYPE="field" FQNAME="rife.bld.extension.dokka.AnalysisPlatform COMMON" />
<entry_point TYPE="field" FQNAME="rife.bld.extension.dokka.AnalysisPlatform JS" />
<entry_point TYPE="field" FQNAME="rife.bld.extension.dokka.AnalysisPlatform NATIVE" />
<entry_point TYPE="field" FQNAME="rife.bld.extension.dokka.DocumentedVisibility INTERNAL" />
<entry_point TYPE="field" FQNAME="rife.bld.extension.dokka.DocumentedVisibility PROTECTED" />
<entry_point TYPE="field" FQNAME="rife.bld.extension.dokka.DocumentedVisibility PUBLIC" />
<entry_point TYPE="field" FQNAME="rife.bld.extension.dokka.LoggingLevel ERROR" />
<entry_point TYPE="field" FQNAME="rife.bld.extension.dokka.LoggingLevel INFO" />
<entry_point TYPE="field" FQNAME="rife.bld.extension.dokka.LoggingLevel PROGRESS" />
<entry_point TYPE="field" FQNAME="rife.bld.extension.dokka.LoggingLevel WARN" />
</entry_points>
<pattern value="rife.bld.extension.CompileKotlinOperationBuild" method="pmd" /> <pattern value="rife.bld.extension.CompileKotlinOperationBuild" method="pmd" />
<pattern value="rife.bld.extension.DokkaOperationBuild" method="pmd" />
<pattern value="rife.bld.extension.dokka.AnalysisPlatform" />
<pattern value="rife.bld.extension.dokka.DocumentedVisibility" />
<pattern value="rife.bld.extension.dokka.LoggingLevel" />
</component> </component>
<component name="ProjectRootManager" version="2" languageLevel="JDK_17" project-jdk-name="17" project-jdk-type="JavaSDK"> <component name="ProjectRootManager" version="2" languageLevel="JDK_17" project-jdk-name="17" project-jdk-type="JavaSDK">
<output url="file://$PROJECT_DIR$/build" /> <output url="file://$PROJECT_DIR$/build" />

View file

@ -28,6 +28,7 @@ import java.util.*;
import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentHashMap;
import java.util.logging.Level; import java.util.logging.Level;
import java.util.logging.Logger; import java.util.logging.Logger;
import java.util.stream.Collectors;
/** /**
* Builds documentation (javadoc, HTML, etc.) using Dokka. * Builds documentation (javadoc, HTML, etc.) using Dokka.
@ -37,6 +38,7 @@ import java.util.logging.Logger;
*/ */
@SuppressWarnings("PMD.AvoidThrowingRawExceptionTypes") @SuppressWarnings("PMD.AvoidThrowingRawExceptionTypes")
public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> { public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
public static final String SEMICOLON = ";";
private final static String GFM_PLUGIN_REGEXP = private final static String GFM_PLUGIN_REGEXP =
"^.*(dokka-base|analysis-kotlin-descriptors|gfm-plugin|freemarker).*\\.jar$"; "^.*(dokka-base|analysis-kotlin-descriptors|gfm-plugin|freemarker).*\\.jar$";
private final static String HTML_PLUGIN_REGEXP = private final static String HTML_PLUGIN_REGEXP =
@ -49,8 +51,8 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
private final Map<String, String> globalLinks_ = new ConcurrentHashMap<>(); private final Map<String, String> globalLinks_ = new ConcurrentHashMap<>();
private final Collection<String> globalPackageOptions_ = new ArrayList<>(); private final Collection<String> globalPackageOptions_ = new ArrayList<>();
private final Collection<String> globalSrcLinks_ = new ArrayList<>(); private final Collection<String> globalSrcLinks_ = new ArrayList<>();
private final Collection<String> includes_ = new ArrayList<>(); private final Collection<File> includes_ = new ArrayList<>();
private final Collection<String> pluginsClasspath_ = new ArrayList<>(); private final Collection<File> pluginsClasspath_ = new ArrayList<>();
private final Map<String, String> pluginsConfiguration_ = new ConcurrentHashMap<>(); private final Map<String, String> pluginsConfiguration_ = new ConcurrentHashMap<>();
private boolean delayTemplateSubstitution_; private boolean delayTemplateSubstitution_;
private boolean failOnWarning_; private boolean failOnWarning_;
@ -81,8 +83,8 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
* @param regex the regular expression to match * @param regex the regular expression to match
* @return the list of JARs * @return the list of JARs
*/ */
public static List<String> getJarList(File directory, String regex) { public static List<File> getJarList(File directory, String regex) {
var jars = new ArrayList<String>(); var jars = new ArrayList<File>();
if (directory.isDirectory()) { if (directory.isDirectory()) {
var files = directory.listFiles(); var files = directory.listFiles();
@ -90,7 +92,7 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
for (var f : files) { for (var f : files) {
if (!f.getName().endsWith("-sources.jar") && (!f.getName().endsWith("-javadoc.jar")) && if (!f.getName().endsWith("-sources.jar") && (!f.getName().endsWith("-javadoc.jar")) &&
f.getName().matches(regex)) { f.getName().matches(regex)) {
jars.add(f.getAbsolutePath()); jars.add(f);
} }
} }
} }
@ -146,12 +148,12 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
// -jar dokka-cli // -jar dokka-cli
args.add("-jar"); args.add("-jar");
args.add(cli.get(0)); args.add(cli.get(0).getAbsolutePath());
// -pluginClasspath // -pluginClasspath
if (!pluginsClasspath_.isEmpty()) { if (!pluginsClasspath_.isEmpty()) {
args.add("-pluginsClasspath"); args.add("-pluginsClasspath");
args.add(String.join(";", pluginsClasspath_)); args.add(pluginsClasspath_.stream().map(File::getAbsolutePath).collect(Collectors.joining(SEMICOLON)));
} }
// -sourceSet // -sourceSet
@ -195,19 +197,19 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
// -globalPackageOptions // -globalPackageOptions
if (!globalPackageOptions_.isEmpty()) { if (!globalPackageOptions_.isEmpty()) {
args.add("-globalPackageOptions"); args.add("-globalPackageOptions");
args.add(String.join(";", globalPackageOptions_)); args.add(String.join(SEMICOLON, globalPackageOptions_));
} }
// -globalSrcLinks // -globalSrcLinks
if (!globalSrcLinks_.isEmpty()) { if (!globalSrcLinks_.isEmpty()) {
args.add("-globalSrcLinks_"); args.add("-globalSrcLinks_");
args.add(String.join(";", globalSrcLinks_)); args.add(String.join(SEMICOLON, globalSrcLinks_));
} }
// -includes // -includes
if (!includes_.isEmpty()) { if (!includes_.isEmpty()) {
args.add("-includes"); args.add("-includes");
args.add(String.join(";", includes_)); args.add(includes_.stream().map(File::getAbsolutePath).collect(Collectors.joining(SEMICOLON)));
} }
// -loggingLevel // -loggingLevel
@ -268,7 +270,7 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
* Configures the operation from a {@link BaseProject}. * Configures the operation from a {@link BaseProject}.
* <p> * <p>
* Sets the {@link #sourceSet sourceSet}, {@link SourceSet#jdkVersion jdkVersion}, {@link #moduleName moduleName} * Sets the {@link #sourceSet sourceSet}, {@link SourceSet#jdkVersion jdkVersion}, {@link #moduleName moduleName}
* and {@link SourceSet#classpath(String...) classpath} from the project. * and {@link SourceSet#classpath(File...) classpath} from the project.
* *
* @param project the project to configure the operation from * @param project the project to configure the operation from
*/ */
@ -276,7 +278,7 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
public DokkaOperation fromProject(BaseProject project) { public DokkaOperation fromProject(BaseProject project) {
project_ = project; project_ = project;
sourceSet_ = new SourceSet() sourceSet_ = new SourceSet()
.src(new File(project.srcMainDirectory(), "kotlin").getAbsolutePath()) .src(new File(project.srcMainDirectory(), "kotlin"))
.classpath(project.compileClasspathJars()) .classpath(project.compileClasspathJars())
.classpath(project.providedClasspathJars()); .classpath(project.providedClasspathJars());
if (project.javaRelease() != null) { if (project.javaRelease() != null) {
@ -302,6 +304,15 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
return this; return this;
} }
/**
* Retrieves the global external documentation links.
*
* @return the documentation links
*/
public Map<String, String> globalLinks() {
return globalLinks_;
}
/** /**
* Set the global external documentation links. * Set the global external documentation links.
* *
@ -348,6 +359,15 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
return this; return this;
} }
/**
* Retrieves the global list of package configurations.
*
* @return the package configurations
*/
public Collection<String> globalPackageOptions() {
return globalPackageOptions_;
}
/** /**
* Sets the global list of package configurations. * Sets the global list of package configurations.
* <p> * <p>
@ -381,6 +401,15 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
return this; return this;
} }
/**
* Retrieves the global source links
*
* @return the source links
*/
public Collection<String> globalSrcLink() {
return globalSrcLinks_;
}
/** /**
* Sets the global mapping between a source directory and a Web service for browsing the code. * Sets the global mapping between a source directory and a Web service for browsing the code.
* *
@ -402,11 +431,37 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
* @param files one or more files * @param files one or more files
* @return this operation instance * @return this operation instance
*/ */
public DokkaOperation includes(String... files) { public DokkaOperation includes(File... files) {
Collections.addAll(includes_, files); Collections.addAll(includes_, files);
return this; 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_, Arrays.stream(files)
.map(File::new)
.toArray(File[]::new));
return this;
}
/**
* Retrieves the markdown files that contain the module and package documentation.
*
* @return the markdown files
*/
public Collection<File> includes() {
return includes_;
}
/** /**
* Sets the Markdown files that contain module and package documentation. * Sets the Markdown files that contain module and package documentation.
* <p> * <p>
@ -417,7 +472,7 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
* @param files the list of files * @param files the list of files
* @return this operation instance * @return this operation instance
*/ */
public DokkaOperation includes(Collection<String> files) { public DokkaOperation includes(Collection<File> files) {
includes_.addAll(files); includes_.addAll(files);
return this; return this;
} }
@ -583,6 +638,26 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
return this; return this;
} }
/**
* Retrieves the plugin configurations.
*
* @return the plugin configurations.
*/
public Map<String, String> pluginConfigurations() {
return pluginsConfiguration_;
}
/**
* Sets the list of jars with Dokka plugins and their dependencies.
*
* @param jars one or more jars
* @return this operation instance
*/
public DokkaOperation pluginsClasspath(File... jars) {
Collections.addAll(pluginsClasspath_, jars);
return this;
}
/** /**
* Sets the list of jars with Dokka plugins and their dependencies. * Sets the list of jars with Dokka plugins and their dependencies.
* *
@ -590,34 +665,32 @@ public class DokkaOperation extends AbstractProcessOperation<DokkaOperation> {
* @return this operation instance * @return this operation instance
*/ */
public DokkaOperation pluginsClasspath(String... jars) { public DokkaOperation pluginsClasspath(String... jars) {
Collections.addAll(pluginsClasspath_, jars); Collections.addAll(pluginsClasspath_, Arrays.stream(jars)
.map(File::new)
.toArray(File[]::new));
return this; return this;
} }
/**
* Retrieves the plugins classpath.
*
* @return the classpath
*/
public Collection<File> pluginsClasspath() {
return pluginsClasspath_;
}
/** /**
* Sets the list of jars with Dokka plugins and their dependencies. * Sets the list of jars with Dokka plugins and their dependencies.
* *
* @param jars the list of jars * @param jars the list of jars
* @return this operation instance * @return this operation instance
*/ */
public DokkaOperation pluginsClasspath(Collection<String> jars) { public DokkaOperation pluginsClasspath(Collection<File> jars) {
pluginsClasspath_.addAll(jars); pluginsClasspath_.addAll(jars);
return this; 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. * Sets the configurations for a source set.
* <p> * <p>

View file

@ -21,6 +21,7 @@ import rife.bld.extension.DokkaOperation;
import java.io.File; import java.io.File;
import java.util.*; import java.util.*;
import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentHashMap;
import java.util.stream.Collectors;
/** /**
* Configuration for a Dokka source set. * Configuration for a Dokka source set.
@ -29,17 +30,16 @@ import java.util.concurrent.ConcurrentHashMap;
* @since 1.0 * @since 1.0
*/ */
public class SourceSet { public class SourceSet {
private static final String SEMICOLON = ";"; private final Collection<File> classpath_ = new ArrayList<>();
private final Collection<String> classpath_ = new ArrayList<>();
private final Map<String, String> dependentSourceSets_ = new ConcurrentHashMap<>(); private final Map<String, String> dependentSourceSets_ = new ConcurrentHashMap<>();
private final Collection<DocumentedVisibility> documentedVisibilities_ = new ArrayList<>(); private final Collection<DocumentedVisibility> documentedVisibilities_ = new ArrayList<>();
private final Map<String, String> externalDocumentationLinks_ = new ConcurrentHashMap<>(); private final Map<String, String> externalDocumentationLinks_ = new ConcurrentHashMap<>();
private final Collection<String> includes_ = new ArrayList<>(); private final Collection<File> includes_ = new ArrayList<>();
private final Collection<String> perPackageOptions_ = new ArrayList<>(); private final Collection<String> perPackageOptions_ = new ArrayList<>();
private final Collection<String> samples_ = new ArrayList<>(); private final Collection<File> samples_ = new ArrayList<>();
private final Map<String, String> srcLinks_ = new ConcurrentHashMap<>(); private final Map<String, String> srcLinks_ = new ConcurrentHashMap<>();
private final Collection<String> src_ = new ArrayList<>(); private final Collection<File> src_ = new ArrayList<>();
private final Collection<String> suppressedFiles_ = new ArrayList<>(); private final Collection<File> suppressedFiles_ = new ArrayList<>();
private AnalysisPlatform analysisPlatform_; private AnalysisPlatform analysisPlatform_;
private String apiVersion_; private String apiVersion_;
private String displayName_; private String displayName_;
@ -110,7 +110,7 @@ public class SourceSet {
// -classpath // -classpath
if (!classpath_.isEmpty()) { if (!classpath_.isEmpty()) {
args.add("-classpath"); args.add("-classpath");
args.add(String.join(SEMICOLON, classpath_)); args.add(classpath_.stream().map(File::getAbsolutePath).collect(Collectors.joining(DokkaOperation.SEMICOLON)));
} }
// -dependentSourceSets // -dependentSourceSets
@ -118,7 +118,7 @@ public class SourceSet {
args.add("-dependentSourceSets"); args.add("-dependentSourceSets");
var deps = new ArrayList<String>(); var deps = new ArrayList<String>();
dependentSourceSets_.forEach((k, v) -> deps.add(String.format("%s/%s", k, v))); dependentSourceSets_.forEach((k, v) -> deps.add(String.format("%s/%s", k, v)));
args.add(String.join(SEMICOLON, deps)); args.add(String.join(DokkaOperation.SEMICOLON, deps));
} }
// -displayName // -displayName
@ -132,7 +132,7 @@ public class SourceSet {
args.add("-documentedVisibilities"); args.add("-documentedVisibilities");
var vis = new ArrayList<String>(); var vis = new ArrayList<String>();
documentedVisibilities_.forEach(d -> vis.add(d.name().toLowerCase())); documentedVisibilities_.forEach(d -> vis.add(d.name().toLowerCase()));
args.add(String.join(SEMICOLON, vis)); args.add(String.join(DokkaOperation.SEMICOLON, vis));
} }
// -externalDocumentationLinks // -externalDocumentationLinks
@ -152,7 +152,7 @@ public class SourceSet {
// -includes // -includes
if (!includes_.isEmpty()) { if (!includes_.isEmpty()) {
args.add("-includes"); args.add("-includes");
args.add(String.join(SEMICOLON, includes_)); args.add(includes_.stream().map(File::getAbsolutePath).collect(Collectors.joining(DokkaOperation.SEMICOLON)));
} }
// -languageVersion // -languageVersion
@ -188,13 +188,13 @@ public class SourceSet {
// -perPackageOptions // -perPackageOptions
if (!perPackageOptions_.isEmpty()) { if (!perPackageOptions_.isEmpty()) {
args.add("-perPackageOptions"); args.add("-perPackageOptions");
args.add(String.join(SEMICOLON, perPackageOptions_)); args.add(String.join(DokkaOperation.SEMICOLON, perPackageOptions_));
} }
// -samples // -samples
if (!samples_.isEmpty()) { if (!samples_.isEmpty()) {
args.add("-samples"); args.add("-samples");
args.add(String.join(SEMICOLON, samples_)); args.add(samples_.stream().map(File::getAbsolutePath).collect(Collectors.joining(DokkaOperation.SEMICOLON)));
} }
// -skipDeprecated // -skipDeprecated
@ -206,7 +206,7 @@ public class SourceSet {
// -src // -src
if (!src_.isEmpty()) { if (!src_.isEmpty()) {
args.add("-src"); args.add("-src");
args.add(String.join(SEMICOLON, src_)); args.add(src_.stream().map(File::getAbsolutePath).collect(Collectors.joining(DokkaOperation.SEMICOLON)));
} }
// -srcLink // -srcLink
@ -214,7 +214,7 @@ public class SourceSet {
args.add("-srcLink"); args.add("-srcLink");
var links = new ArrayList<String>(); var links = new ArrayList<String>();
srcLinks_.forEach((k, v) -> links.add(String.format("%s=%s", k, v))); srcLinks_.forEach((k, v) -> links.add(String.format("%s=%s", k, v)));
args.add(String.join(SEMICOLON, links)); args.add(String.join(DokkaOperation.SEMICOLON, links));
} }
// -sourceSetName // -sourceSetName
@ -226,7 +226,7 @@ public class SourceSet {
// -suppressedFiles // -suppressedFiles
if (!suppressedFiles_.isEmpty()) { if (!suppressedFiles_.isEmpty()) {
args.add("-suppressedFiles"); args.add("-suppressedFiles");
args.add(String.join(SEMICOLON, suppressedFiles_)); args.add(suppressedFiles_.stream().map(File::getAbsolutePath).collect(Collectors.joining(DokkaOperation.SEMICOLON)));
} }
return args; return args;
@ -242,7 +242,7 @@ public class SourceSet {
* @param files one or more file * @param files one or more file
* @return this operation instance * @return this operation instance
*/ */
public SourceSet classpath(String... files) { public SourceSet classpath(File... files) {
Collections.addAll(classpath_, files); Collections.addAll(classpath_, files);
return this; return this;
} }
@ -254,11 +254,13 @@ public class SourceSet {
* <p> * <p>
* This option accepts both {@code .jar} and {@code .klib} files. * This option accepts both {@code .jar} and {@code .klib} files.
* *
* @param files the list of files * @param files one or more file
* @return this operation instance * @return this operation instance
*/ */
public SourceSet classpath(Collection<String> files) { public SourceSet classpath(String... files) {
classpath_.addAll(files); Collections.addAll(classpath_, Arrays.stream(files)
.map(File::new)
.toArray(File[]::new));
return this; return this;
} }
@ -272,11 +274,20 @@ public class SourceSet {
* @param files the list of files * @param files the list of files
* @return this operation instance * @return this operation instance
*/ */
public SourceSet classpath(List<File> files) { public SourceSet classpath(Collection<File> files) {
files.forEach(it -> classpath_.add(it.getAbsolutePath())); classpath_.addAll(files);
return this; return this;
} }
/**
* Retrieves the classpath for analysis and interactive samples.
*
* @return the classpath
*/
public Collection<File> classpath() {
return classpath_;
}
/** /**
* Sets the names of dependent source sets. * Sets the names of dependent source sets.
* *
@ -289,6 +300,15 @@ public class SourceSet {
return this; return this;
} }
/**
* Retrieves the names of dependent source sets.
*
* @return the names
*/
public Map<String, String> dependentSourceSets() {
return dependentSourceSets_;
}
/** /**
* Sets the names of dependent source sets. * Sets the names of dependent source sets.
* *
@ -333,6 +353,15 @@ public class SourceSet {
return this; return this;
} }
/**
* Retrieves the visibilities to be documented.
*
* @return the documented visibilities
*/
public Collection<DocumentedVisibility> documentedVisibilities() {
return documentedVisibilities_;
}
/** /**
* Sets the external documentation links. * Sets the external documentation links.
* <p> * <p>
@ -347,6 +376,15 @@ public class SourceSet {
return this; return this;
} }
/**
* Retrieves the external documentation links.
*
* @return the documentation links.
*/
public Map<String, String> externalDocumentationLinks() {
return externalDocumentationLinks_;
}
/** /**
* Sets the external documentation links. * Sets the external documentation links.
* <p> * <p>
@ -372,11 +410,38 @@ public class SourceSet {
* @param files one or more files * @param files one or more files
* @return this operation instance * @return this operation instance
*/ */
public SourceSet includes(String... files) { public SourceSet includes(File... files) {
Collections.addAll(includes_, files); Collections.addAll(includes_, files);
return this; 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_, Arrays.stream(files)
.map(File::new)
.toArray(File[]::new));
return this;
}
/**
* Retrieves the Markdown files that contain module and package documentation.
*
* @return the markdown files
*/
public Collection<File> includes() {
return includes_;
}
/** /**
* Sets the Markdown files that contain module and package documentation. * Sets the Markdown files that contain module and package documentation.
* <p> * <p>
@ -388,7 +453,7 @@ public class SourceSet {
* @param files the list of files * @param files the list of files
* @return this operation instance * @return this operation instance
*/ */
public SourceSet includes(Collection<String> files) { public SourceSet includes(Collection<File> files) {
includes_.addAll(files); includes_.addAll(files);
return this; return this;
} }
@ -517,6 +582,15 @@ public class SourceSet {
return this; return this;
} }
/**
* Retrieves the list of package source set configuration.
*
* @return the package source set configuration
*/
public Collection<String> perPackageOptions() {
return perPackageOptions_;
}
/** /**
* Set the list of package source set configuration. * Set the list of package source set configuration.
* <p> * <p>
@ -568,11 +642,34 @@ public class SourceSet {
* @param samples the list of samples * @param samples the list of samples
* @return this operation instance * @return this operation instance
*/ */
public SourceSet samples(Collection<String> samples) { public SourceSet samples(Collection<File> samples) {
samples_.addAll(samples); samples_.addAll(samples);
return this; return this;
} }
/**
* Retrieves the list of directories or files that contain sample functions.
*
* @return the directories or files
*/
public Collection<File> samples() {
return samples_;
}
/**
* 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(File... samples) {
Collections.addAll(samples_, samples);
return this;
}
/** /**
* Set the list of directories or files that contain sample functions. * Set the list of directories or files that contain sample functions.
* <p> * <p>
@ -583,7 +680,9 @@ public class SourceSet {
* @return this operation instance * @return this operation instance
*/ */
public SourceSet samples(String... samples) { public SourceSet samples(String... samples) {
Collections.addAll(samples_, samples); Collections.addAll(samples_, Arrays.stream(samples)
.map(File::new)
.toArray(File[]::new));
return this; return this;
} }
@ -622,7 +721,7 @@ public class SourceSet {
* @param src the list of source code roots * @param src the list of source code roots
* @return this operation instance * @return this operation instance
*/ */
public SourceSet src(Collection<String> src) { public SourceSet src(Collection<File> src) {
src_.addAll(src); src_.addAll(src);
return this; return this;
} }
@ -636,11 +735,36 @@ public class SourceSet {
* @param src pne ore moe source code roots * @param src pne ore moe source code roots
* @return this operation instance * @return this operation instance
*/ */
public SourceSet src(String... src) { public SourceSet src(File... src) {
Collections.addAll(src_, src); Collections.addAll(src_, src);
return this; 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_, Arrays.stream(src)
.map(File::new)
.toArray(File[]::new));
return this;
}
/**
* Retrieves the source code roots to be analyzed and documented.
*
* @return the source code roots
*/
public Collection<File> src() {
return src_;
}
/** /**
* Sets the mapping between a source directory and a Web service for browsing the code. * Sets the mapping between a source directory and a Web service for browsing the code.
* *
@ -654,6 +778,28 @@ public class SourceSet {
return this; 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(File srcPath, String remotePath, String lineSuffix) {
srcLinks_.put(srcPath.getAbsolutePath(), remotePath + lineSuffix);
return this;
}
/**
* Retrieves the mapping between a source directory and a Web service for browsing the code.
*
* @return the source links
*/
public Map<String, String> srcLinks() {
return srcLinks_;
}
/** /**
* Sets the paths to files to be suppressed. * Sets the paths to files to be suppressed.
* <p> * <p>
@ -662,11 +808,21 @@ public class SourceSet {
* @param suppressedFiles the list of suppressed files * @param suppressedFiles the list of suppressed files
* @return this operation instance * @return this operation instance
*/ */
public SourceSet suppressedFiles(Collection<String> suppressedFiles) { public SourceSet suppressedFiles(Collection<File> suppressedFiles) {
suppressedFiles_.addAll(suppressedFiles); suppressedFiles_.addAll(suppressedFiles);
return this; return this;
} }
/**
* Retrieves the paths to files to be suppressed.
*
* @return the paths
*/
public Collection<File> suppressedFiles() {
return suppressedFiles_;
}
/** /**
* Sets the paths to files to be suppressed. * Sets the paths to files to be suppressed.
* <p> * <p>
@ -676,6 +832,21 @@ public class SourceSet {
* @return this operation instance * @return this operation instance
*/ */
public SourceSet suppressedFiles(String... suppressedFiles) { public SourceSet suppressedFiles(String... suppressedFiles) {
Collections.addAll(suppressedFiles_, Arrays.stream(suppressedFiles)
.map(File::new)
.toArray(File[]::new));
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(File... suppressedFiles) {
suppressedFiles_.addAll(Arrays.asList(suppressedFiles)); suppressedFiles_.addAll(Arrays.asList(suppressedFiles));
return this; return this;
} }

View file

@ -35,7 +35,7 @@ import static org.assertj.core.api.Assertions.assertThat;
class DokkaOperationTest { class DokkaOperationTest {
@Test @Test
@SuppressWarnings({"ExtractMethodRecommender", "PMD.AvoidDuplicateLiterals"}) @SuppressWarnings({"PMD.AvoidDuplicateLiterals"})
void executeConstructProcessCommandListTest() throws IOException { void executeConstructProcessCommandListTest() throws IOException {
var args = Files.readAllLines(Paths.get("src", "test", "resources", "dokka-args.txt")); var args = Files.readAllLines(Paths.get("src", "test", "resources", "dokka-args.txt"));
@ -43,7 +43,7 @@ class DokkaOperationTest {
var examples = new File("examples"); var examples = new File("examples");
var jsonConf = new File("config.json"); var jsonConf = new File("config.json");
var params = new DokkaOperation() var op = new DokkaOperation()
.delayTemplateSubstitution(true) .delayTemplateSubstitution(true)
.failOnWarning(true) .failOnWarning(true)
.fromProject(new BaseProjectBlueprint(examples, "com.example", "Example")) .fromProject(new BaseProjectBlueprint(examples, "com.example", "Example"))
@ -53,8 +53,9 @@ class DokkaOperationTest {
.globalPackageOptions(List.of("option3", "option4")) .globalPackageOptions(List.of("option3", "option4"))
.globalSrcLink("link1", "link2") .globalSrcLink("link1", "link2")
.globalSrcLink(List.of("link3", "link4")) .globalSrcLink(List.of("link3", "link4"))
.includes("file1", "file2") .includes(new File("file1"))
.includes(List.of("file3", "file4")) .includes("file2")
.includes(List.of(new File("file3"), new File("file4")))
.json(jsonConf) .json(jsonConf)
.loggingLevel(LoggingLevel.DEBUG) .loggingLevel(LoggingLevel.DEBUG)
.moduleName("name") .moduleName("name")
@ -65,16 +66,24 @@ class DokkaOperationTest {
.outputFormat(OutputFormat.JAVADOC) .outputFormat(OutputFormat.JAVADOC)
.pluginConfigurations("name", "{\"json\"}") .pluginConfigurations("name", "{\"json\"}")
.pluginConfigurations(Map.of("{\"name2\"}", "json2", "name3}", "{json3")) .pluginConfigurations(Map.of("{\"name2\"}", "json2", "name3}", "{json3"))
.pluginsClasspath("path1", "path2") .pluginsClasspath(new File("path1"))
.pluginsClasspath(List.of("path3", "path4")) .pluginsClasspath("path2")
.pluginsClasspath(List.of(new File("path3"), new File("path4")))
.sourceSet(new SourceSet().classpath( .sourceSet(new SourceSet().classpath(
List.of( List.of(
new File("examples/foo.jar"), new File("examples/foo.jar"),
new File("examples/bar.jar") new File("examples/bar.jar")
))) )))
.suppressInheritedMembers(true) .suppressInheritedMembers(true);
.executeConstructProcessCommandList();
assertThat(op.globalLinks()).as("globalLinks").hasSize(2);
assertThat(op.globalPackageOptions()).as("globalPackageOptions").hasSize(4);
assertThat(op.globalSrcLink()).as("globalSrcLink").hasSize(4);
assertThat(op.includes()).as("includes").hasSize(4);
assertThat(op.pluginConfigurations()).as("pluginConfigurations").hasSize(3);
assertThat(op.pluginsClasspath()).as("pluginsClasspath").hasSize(9);
var params = op.executeConstructProcessCommandList();
for (var p : args) { for (var p : args) {
var found = false; var found = false;
for (var a : params) { for (var a : params) {
@ -94,15 +103,17 @@ class DokkaOperationTest {
path + "/lib/bld/analysis-kotlin-descriptors-" + dokkaJar + ';' + path + "/lib/bld/analysis-kotlin-descriptors-" + dokkaJar + ';' +
path + "/lib/bld/javadoc-plugin-" + dokkaJar + ';' + path + "/lib/bld/javadoc-plugin-" + dokkaJar + ';' +
path + "/lib/bld/korte-jvm-4.0.10.jar;" + path + "/lib/bld/korte-jvm-4.0.10.jar;" +
path + "/lib/bld/kotlin-as-java-plugin-" + dokkaJar + ";path1;path2;path3;path4", path + "/lib/bld/kotlin-as-java-plugin-" + dokkaJar + ';' +
"-sourceSet", "-src " + path + "/src/main/kotlin" + " -classpath " + path + "/foo.jar;" + path + "/bar.jar", TestUtil.localPath("path1", "path2", "path3", "path4"),
"-sourceSet", "-src " + path + "/src/main/kotlin" + " -classpath " + path + "/foo.jar;"
+ path + "/bar.jar",
"-outputDir", path + "/build", "-outputDir", path + "/build",
"-delayTemplateSubstitution", "-delayTemplateSubstitution",
"-failOnWarning", "-failOnWarning",
"-globalLinks", "s^link^^s2^link2", "-globalLinks", "s^link^^s2^link2",
"-globalPackageOptions", "option1;option2;option3;option4", "-globalPackageOptions", "option1;option2;option3;option4",
"-globalSrcLinks_", "link1;link2;link3;link4", "-globalSrcLinks_", "link1;link2;link3;link4",
"-includes", "file1;file2;file3;file4", "-includes", TestUtil.localPath("file1", "file2", "file3", "file4"),
"-loggingLevel", "debug", "-loggingLevel", "debug",
"-moduleName", "name", "-moduleName", "name",
"-moduleVersion", "1.0", "-moduleVersion", "1.0",

View file

@ -0,0 +1,40 @@
/*
* 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;
import java.io.File;
import java.util.Arrays;
import java.util.stream.Collectors;
import static rife.bld.extension.DokkaOperation.SEMICOLON;
@SuppressWarnings("PMD.TestClassWithoutTestCases")
public final class TestUtil {
private TestUtil() {
// no-op
}
/**
* Returns the local path of the given file names.
*
* @param fileNames The file names
* @return the local path
*/
public static String localPath(String... fileNames) {
return Arrays.stream(fileNames).map(it -> new File(it).getAbsolutePath()).collect(Collectors.joining(SEMICOLON));
}
}

View file

@ -14,13 +14,11 @@
* limitations under the License. * limitations under the License.
*/ */
package rife.bld.extension; package rife.bld.extension.dokka;
import org.junit.jupiter.api.Test; import org.junit.jupiter.api.Test;
import rife.bld.extension.dokka.AnalysisPlatform;
import rife.bld.extension.dokka.DocumentedVisibility;
import rife.bld.extension.dokka.SourceSet;
import java.io.File;
import java.io.IOException; import java.io.IOException;
import java.nio.file.Files; import java.nio.file.Files;
import java.nio.file.Paths; import java.nio.file.Paths;
@ -29,26 +27,36 @@ import java.util.Map;
import java.util.stream.IntStream; import java.util.stream.IntStream;
import static org.assertj.core.api.Assertions.assertThat; import static org.assertj.core.api.Assertions.assertThat;
import static rife.bld.extension.TestUtil.localPath;
class SourceSetTest { class SourceSetTest {
public static final String SAMPLES_1 = "samples1";
public static final String SAMPLES_2 = "samples2";
public static final String SUP_1 = "sup1";
public static final String SUP_2 = "sup2";
@Test @Test
void sourceSetCollectionsTest() { void sourceSetCollectionsTest() {
var args = new SourceSet() var args = new SourceSet()
.classpath(List.of("path1", "path2")) .classpath(List.of(new File("path1"), new File("path2")))
.dependentSourceSets(Map.of("set1", "set2", "set3", "set4")) .dependentSourceSets(Map.of("set1", "set2", "set3", "set4"))
.externalDocumentationLinks(Map.of("link1", "link2", "link3", "link4")) .externalDocumentationLinks(Map.of("link1", "link2", "link3", "link4"))
.perPackageOptions(List.of("option1", "option2")) .perPackageOptions(List.of("option1", "option2"))
.samples(List.of("samples1", "samples1")) .samples(List.of(new File(SAMPLES_1)))
.suppressedFiles(List.of("sup1", "sup2")) .samples(new File(SAMPLES_2))
.samples("samples3")
.suppressedFiles(List.of(new File(SUP_1)))
.suppressedFiles(new File(SUP_2))
.suppressedFiles("sup3")
.args(); .args();
var matches = List.of( var matches = List.of(
"-classpath", "path1;path2", "-classpath", localPath("path1", "path2"),
"-dependentSourceSets", "set1/set2;set3/set4", "-dependentSourceSets", "set1/set2;set3/set4",
"-externalDocumentationLinks", "link3^link4^^link1^link2", "-externalDocumentationLinks", "link3^link4^^link1^link2",
"-perPackageOptions", "option1;option2", "-perPackageOptions", "option1;option2",
"-samples", "samples1;samples1", "-samples", localPath(SAMPLES_1, SAMPLES_2, "samples3"),
"-suppressedFiles", "sup1;sup2" "-suppressedFiles", localPath(SUP_1, SUP_2, "sup3")
); );
assertThat(args).hasSize(matches.size()); assertThat(args).hasSize(matches.size());
@ -66,13 +74,17 @@ class SourceSetTest {
var sourceSet = new SourceSet() var sourceSet = new SourceSet()
.analysisPlatform(AnalysisPlatform.JVM) .analysisPlatform(AnalysisPlatform.JVM)
.apiVersion("1.0") .apiVersion("1.0")
.classpath("classpath1", "classpath2") .classpath("classpath1")
.classpath(new File("classpath2"))
.dependentSourceSets("moduleName", "sourceSetName") .dependentSourceSets("moduleName", "sourceSetName")
.dependentSourceSets("moduleName2", "sourceSetName2")
.displayName("name") .displayName("name")
.documentedVisibilities(DocumentedVisibility.PACKAGE, DocumentedVisibility.PRIVATE) .documentedVisibilities(DocumentedVisibility.PACKAGE, DocumentedVisibility.PRIVATE)
.externalDocumentationLinks("url1", "packageListUrl1") .externalDocumentationLinks("url1", "packageListUrl1")
.externalDocumentationLinks("url2", "packageListUrl2") .externalDocumentationLinks("url2", "packageListUrl2")
.includes("includes1", "includes2") .includes("includes1", "includes2")
.includes(new File("includes3"))
.includes(List.of(new File("includes4")))
.jdkVersion(18) .jdkVersion(18)
.languageVersion("2.0") .languageVersion("2.0")
.noJdkLink(true) .noJdkLink(true)
@ -80,13 +92,26 @@ class SourceSetTest {
.noStdlibLink(true) .noStdlibLink(true)
.perPackageOptions("options1", "options2") .perPackageOptions("options1", "options2")
.reportUndocumented(true) .reportUndocumented(true)
.samples("samples1", "sample2") .samples(SAMPLES_1, SAMPLES_2)
.skipDeprecated(true) .skipDeprecated(true)
.sourceSetName("setName") .sourceSetName("setName")
.src("src1", "src2") .src("src1", "src2")
.src(new File("src3"))
.src(List.of(new File("src4")))
.srcLink("path1", "remote1", "#suffix1") .srcLink("path1", "remote1", "#suffix1")
.srcLink("path2", "remote2", "#suffix2") .srcLink(new File("path2"), "remote2", "#suffix2")
.suppressedFiles("sup1", "sup2"); .suppressedFiles(SUP_1, SUP_2);
assertThat(sourceSet.classpath()).as("classpath").hasSize(2);
assertThat(sourceSet.dependentSourceSets()).as("dependentSourceSets").hasSize(2);
assertThat(sourceSet.documentedVisibilities()).as("documentedVisibilities").hasSize(2);
assertThat(sourceSet.externalDocumentationLinks()).as("externalDocumentationLinks").hasSize(2);
assertThat(sourceSet.includes()).as("includes").hasSize(4);
assertThat(sourceSet.perPackageOptions()).as("perPackageOptions").hasSize(2);
assertThat(sourceSet.samples()).as("samples").hasSize(2);
assertThat(sourceSet.src()).as("src").hasSize(4);
assertThat(sourceSet.srcLinks()).as("srcLinks").hasSize(2);
assertThat(sourceSet.suppressedFiles()).as("suppressedFiles").hasSize(2);
var params = sourceSet.args(); var params = sourceSet.args();
@ -104,31 +129,31 @@ class SourceSetTest {
var matches = List.of( var matches = List.of(
"-analysisPlatform", "jvm", "-analysisPlatform", "jvm",
"-apiVersion", "1.0", "-apiVersion", "1.0",
"-classpath", "classpath1;classpath2", "-classpath", localPath("classpath1", "classpath2"),
"-dependentSourceSets", "moduleName/sourceSetName", "-dependentSourceSets", "moduleName/sourceSetName;moduleName2/sourceSetName2",
"-displayName", "name", "-displayName", "name",
"-documentedVisibilities", "package;private", "-documentedVisibilities", "package;private",
"-externalDocumentationLinks", "url1^packageListUrl1^^url2^packageListUrl2", "-externalDocumentationLinks", "url1^packageListUrl1^^url2^packageListUrl2",
"-jdkVersion", "18", "-jdkVersion", "18",
"-includes", "includes1;includes2", "-includes", localPath("includes1", "includes2", "includes3", "includes4"),
"-languageVersion", "2.0", "-languageVersion", "2.0",
"-noJdkLink", "true", "-noJdkLink", "true",
"-noSkipEmptyPackages", "true", "-noSkipEmptyPackages", "true",
"-noStdlibLink", "true", "-noStdlibLink", "true",
"-reportUndocumented", "true", "-reportUndocumented", "true",
"-perPackageOptions", "options1;options2", "-perPackageOptions", "options1;options2",
"-samples", "samples1;sample2", "-samples", localPath(SAMPLES_1, SAMPLES_2),
"-skipDeprecated", "true", "-skipDeprecated", "true",
"-src", "src1;src2", "-src", localPath("src1", "src2", "src3", "src4"),
"-srcLink", "path1=remote1#suffix1;path2=remote2#suffix2", "-srcLink", localPath("path2") + "=remote2#suffix2;path1=remote1#suffix1",
"-sourceSetName", "setName", "-sourceSetName", "setName",
"-suppressedFiles", "sup1;sup2"); "-suppressedFiles", localPath(SUP_1, SUP_2));
assertThat(params).hasSize(matches.size()); assertThat(params).hasSize(matches.size());
IntStream.range(0, params.size()).forEach(i -> assertThat(params.get(i)).isEqualTo(matches.get(i))); IntStream.range(0, params.size()).forEach(i -> assertThat(params.get(i)).isEqualTo(matches.get(i)));
sourceSet.classpath(List.of("classpath1", "classpath2")); sourceSet.classpath(List.of(new File("classpath1"), new File("classpath2")));
IntStream.range(0, params.size()).forEach(i -> assertThat(params.get(i)).isEqualTo(matches.get(i))); IntStream.range(0, params.size()).forEach(i -> assertThat(params.get(i)).isEqualTo(matches.get(i)));
} }