Package rife.bld.extension

Class DokkaOperation

java.lang.Object
rife.bld.operations.AbstractOperation<T>
rife.bld.operations.AbstractProcessOperation<DokkaOperation>
rife.bld.extension.DokkaOperation
public class DokkaOperation extends AbstractProcessOperation<DokkaOperation>
Builds documentation (javadoc, HTML, etc.) using Dokka.
Since:
1.0
Author:
Erik C. Thauvin

  • Field Details

  • Constructor Details

    • DokkaOperation

      public DokkaOperation()

  • Method Details

    • getJarList

      public static List<File> getJarList(File directory, String regex)
      Returns the JARs contained in a given directory.

      Sources and Javadoc JARs are ignored.

      Parameters:
      directory - the directory
      regex - the regular expression to match
      Returns:
      the Java Archives

    • isNotBlank

      public static boolean isNotBlank(String s)
      Determines if the given string is not blank.
      Parameters:
      s - the string
      Returns:
      true if not blank, false otherwise.

    • delayTemplateSubstitution

      public DokkaOperation delayTemplateSubstitution(Boolean delayTemplateSubstitution)
      Sets the delay substitution of some elements.

      Used in incremental builds of multimodule projects.

      Parameters:
      delayTemplateSubstitution - the delay
      Returns:
      this operation instance

    • execute

      public void execute() throws IOException, InterruptedException, ExitStatusException
      Overrides:
      execute in class AbstractProcessOperation<DokkaOperation>
      Throws:
      IOException
      InterruptedException
      ExitStatusException

    • executeConstructProcessCommandList

      protected List<String> executeConstructProcessCommandList()
      Part of the execute operation, constructs the command list to use for building the process.
      Specified by:
      executeConstructProcessCommandList in class AbstractProcessOperation<DokkaOperation>
      Since:
      1.5

    • fromProject

      public DokkaOperation fromProject(BaseProject project)
      Configures the operation from a BaseProject.

      Sets the sourceSet, jdkVersion, moduleName and classpath from the project.

      Specified by:
      fromProject in class AbstractProcessOperation<DokkaOperation>
      Parameters:
      project - the project to configure the operation from

    • failOnWarning

      public DokkaOperation failOnWarning(Boolean failOnWarning)
      Sets whether to fail documentation generation if Dokka has emitted a warning or an error.

      Whether to fail documentation generation if Dokka has emitted a warning or an error. The process waits until all errors and warnings have been emitted first.

      This setting works well with SourceSet.reportUndocumented(java.lang.Boolean)

      Parameters:
      failOnWarning - true or false
      Returns:
      this operation instance

    • globalLinks

      public Map<String,String> globalLinks()
      Retrieves the global external documentation links.
      Returns:
      the documentation links

    • globalLinks

      public DokkaOperation globalLinks(String url, String packageListUrl)
      Set the global external documentation links.
      Parameters:
      url - the external documentation URL
      packageListUrl - the external documentation package list URL
      Returns:
      this operation instance

    • globalLinks

      public DokkaOperation globalLinks(Map<String,String> globalLinks)
      Set the global external documentation links.
      Parameters:
      globalLinks - the map of global links
      Returns:
      this operation instance
      See Also:

    • globalPackageOptions

      public DokkaOperation globalPackageOptions(String... options)
      Sets the global package configurations.

      Using format:

      • matchingRegexp
      • -deprecated
      • -privateApi
      • +warnUndocumented
      • +suppress
      • +visibility:PUBLIC
      • ...
      Parameters:
      options - ome pr more package configurations
      Returns:
      this operation instance

    • globalPackageOptions

      public Collection<String> globalPackageOptions()
      Retrieves the global package configurations.
      Returns:
      the package configurations

    • globalPackageOptions

      public DokkaOperation globalPackageOptions(Collection<String> options)
      Sets the global package configurations.

      Using format:

      • matchingRegexp
      • -deprecated
      • -privateApi
      • +warnUndocumented
      • +suppress
      • +visibility:PUBLIC
      • ...
      Parameters:
      options - the package configurations
      Returns:
      this operation instance

    • globalSrcLink

      public DokkaOperation globalSrcLink(String... links)
      Sets the global mapping between a source directory and a Web service for browsing the code.
      Parameters:
      links - one or more links mapping
      Returns:
      this operation instance

    • globalSrcLink

      public Collection<String> globalSrcLink()
      Retrieves the global source links
      Returns:
      the source links

    • globalSrcLink

      public DokkaOperation globalSrcLink(Collection<String> links)
      Sets the global mapping between a source directory and a Web service for browsing the code.
      Parameters:
      links - the links mapping
      Returns:
      this operation instance

    • includes

      public DokkaOperation includes(File... files)
      Sets the Markdown files that contain module and package documentation.

      The contents of specified files are parsed and embedded into documentation as module and package descriptions.

      This can be configured on per-package basis.

      Parameters:
      files - one or more files
      Returns:
      this operation instance
      See Also:

    • includes

      public DokkaOperation includes(String... files)
      Sets the Markdown files that contain module and package documentation.

      The contents of specified files are parsed and embedded into documentation as module and package descriptions.

      This can be configured on per-package basis.

      Parameters:
      files - one or more files
      Returns:
      this operation instance
      See Also:

    • includes

      public DokkaOperation includes(Path... files)
      Sets the Markdown files that contain module and package documentation.

      The contents of specified files are parsed and embedded into documentation as module and package descriptions.

      This can be configured on per-package basis.

      Parameters:
      files - one or more files
      Returns:
      this operation instance
      See Also:

    • includes

      public Collection<File> includes()
      Retrieves the markdown files that contain the module and package documentation.
      Returns:
      the markdown files

    • includes

      public DokkaOperation includes(Collection<File> files)
      Sets the Markdown files that contain module and package documentation.

      The contents of specified files are parsed and embedded into documentation as module and package descriptions.

      This can be configured on per-package basis.

      Parameters:
      files - the markdown files
      Returns:
      this operation instance
      See Also:

    • includesPaths

      public DokkaOperation includesPaths(Collection<Path> files)
      Sets the Markdown files that contain module and package documentation.

      The contents of specified files are parsed and embedded into documentation as module and package descriptions.

      This can be configured on per-package basis.

      Parameters:
      files - the markdown files
      Returns:
      this operation instance
      See Also:

    • includesStrings

      public DokkaOperation includesStrings(Collection<String> files)
      Sets the Markdown files that contain module and package documentation.

      The contents of specified files are parsed and embedded into documentation as module and package descriptions.

      This can be configured on per-package basis.

      Parameters:
      files - the markdown files
      Returns:
      this operation instance
      See Also:

    • json

      public DokkaOperation json(File configuration)
      JSON configuration file path.
      Parameters:
      configuration - the configuration file path

    • json

      public DokkaOperation json(Path configuration)
      JSON configuration file path.
      Parameters:
      configuration - the configuration file path

    • json

      public File json()
      Retrieves the JSON configuration file path.
      Returns:
      the configuration file path

    • json

      public DokkaOperation json(String configuration)
      JSON configuration file path.
      Parameters:
      configuration - the configuration file path

    • loggingLevel

      public DokkaOperation loggingLevel(LoggingLevel loggingLevel)
      Sets the logging level.
      Parameters:
      loggingLevel - the logging level
      Returns:
      this operation instance

    • moduleName

      public DokkaOperation moduleName(String moduleName)
      Sets the name of the project/module. Default is root.

      The display name used to refer to the module. It is used for the table of contents, navigation, logging, etc.

      Parameters:
      moduleName - the project/module name
      Returns:
      this operation instance

    • moduleVersion

      public DokkaOperation moduleVersion(String version)
      Set the documented version.
      Parameters:
      version - the version
      Returns:
      this operation instance

    • noSuppressObviousFunctions

      public DokkaOperation noSuppressObviousFunctions(Boolean noSuppressObviousFunctions)
      Sets whether to suppress obvious functions such as inherited from kotlin.Any and Object.

      A function is considered to be obvious if it is:

      • Inherited from kotlin.Any, Kotlin.Enum, Object or Enum, such as equals, hashCode, toString.
      • Synthetic (generated by the compiler) and does not have any documentation, such as dataClass.componentN or dataClass.copy.
      Parameters:
      noSuppressObviousFunctions - true or false
      Returns:
      this operation instance

    • offlineMode

      public DokkaOperation offlineMode(Boolean offlineMode)
      Sets whether to resolve remote files/links over network.

      This includes package-lists used for generating external documentation links. For example, to make classes from the standard library clickable.

      Setting this to true can significantly speed up build times in certain cases, but can also worsen documentation quality and user experience. For example, by not resolving class/member links from your dependencies, including the standard library.

      Note: You can cache fetched files locally and provide them to Dokka as local paths.

      Parameters:
      offlineMode - the offline mode
      Returns:
      this operation instance
      See Also:

    • outputDir

      public DokkaOperation outputDir(File outputDir)
      Sets the output directory path, ./dokka by default.

      The directory to where documentation is generated, regardless of output format.

      Parameters:
      outputDir - the output directory
      Returns:
      this operation instance

    • outputDir

      public File outputDir()
      Retrieves the output directory path.
      Returns:
      the output directory

    • outputDir

      public DokkaOperation outputDir(String outputDir)
      Sets the output directory path, ./dokka by default.

      The directory to where documentation is generated, regardless of output format.

      Parameters:
      outputDir - the output directory
      Returns:
      this operation instance

    • outputDir

      public DokkaOperation outputDir(Path outputDir)
      Sets the output directory path, ./dokka by default.

      The directory to where documentation is generated, regardless of output format.

      Parameters:
      outputDir - the output directory
      Returns:
      this operation instance

    • outputFormat

      public DokkaOperation outputFormat(OutputFormat format)
      Sets the Dokka output format.
      Parameters:
      format - The output format
      Returns:
      this operation instance

    • pluginConfigurations

      public DokkaOperation pluginConfigurations(String name, String jsonConfiguration)
      Sets the configuration for Dokka plugins.
      Parameters:
      name - The fully-qualified plugin name
      jsonConfiguration - The plugin JSON configuration
      Returns:
      this operation instance

    • pluginConfigurations

      public DokkaOperation pluginConfigurations(Map<String,String> pluginConfigurations)
      Sets the configuration for Dokka plugins.
      Parameters:
      pluginConfigurations - the map of configurations
      Returns:
      this operation instance
      See Also:

    • pluginConfigurations

      public Map<String,String> pluginConfigurations()
      Retrieves the plugin configurations.
      Returns:
      the plugin configurations.

    • pluginsClasspath

      public DokkaOperation pluginsClasspath(File... jars)
      Sets the jars for Dokka plugins and their dependencies.
      Parameters:
      jars - one or more jars
      Returns:
      this operation instance
      See Also:

    • pluginsClasspath

      public DokkaOperation pluginsClasspath(String... jars)
      Sets the jars for Dokka plugins and their dependencies.
      Parameters:
      jars - one or more jars
      Returns:
      this operation instance
      See Also:

    • pluginsClasspath

      public DokkaOperation pluginsClasspath(Path... jars)
      Sets the jars for Dokka plugins and their dependencies.
      Parameters:
      jars - one or more jars
      Returns:
      this operation instance
      See Also:

    • pluginsClasspath

      public Collection<File> pluginsClasspath()
      Retrieves the plugins classpath.
      Returns:
      the classpath

    • pluginsClasspath

      public DokkaOperation pluginsClasspath(Collection<File> jars)
      Sets the jars for Dokka plugins and their dependencies.
      Parameters:
      jars - the jars
      Returns:
      this operation instance
      See Also:

    • pluginsClasspathPaths

      public DokkaOperation pluginsClasspathPaths(Collection<Path> jars)
      Sets the jars for Dokka plugins and their dependencies.
      Parameters:
      jars - the jars
      Returns:
      this operation instance
      See Also:

    • pluginsClasspathStrings

      public DokkaOperation pluginsClasspathStrings(Collection<String> jars)
      Sets the jars for Dokka plugins and their dependencies.
      Parameters:
      jars - the jars
      Returns:
      this operation instance
      See Also:

    • sourceSet

      public DokkaOperation sourceSet(SourceSet sourceSet)
      Sets the configurations for a source set.

      Individual and additional configuration of Kotlin source sets.

      Parameters:
      sourceSet - the source set configurations
      Returns:
      this operation instance

    • suppressInheritedMembers

      public DokkaOperation suppressInheritedMembers(Boolean suppressInheritedMembers)
      Sets whether to suppress inherited members that aren't explicitly overridden in a given class.
      Parameters:
      suppressInheritedMembers - true or false
      Returns:
      this operation instance