Package rife.bld.extension

Class DokkaOperation

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

  • Field Details

    • DOKKA_LIST_SEPARATOR

      public static final String DOKKA_LIST_SEPARATOR
      Separator used by Dokka CLI between list items in a single argument value.
      See Also:

    • DOKKA_VERSION

      public static final Version DOKKA_VERSION
      The Dokka version.

  • Constructor Details

    • DokkaOperation

      public DokkaOperation()

  • Method Details

    • execute

      public void execute() throws IOException, InterruptedException, ExitStatusException
      Performs this operation.
      Overrides:
      execute in class AbstractProcessOperation<DokkaOperation>
      Throws:
      NullPointerException - if project or outputformat or sourceSet is null
      IllegalArgumentException - if json is null or does not exist
      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, if not already set.

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

    • 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

    • 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(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
      Throws:
      NullPointerException - if url or packageListUrl is null
      IllegalArgumentException - if url or packageListUrl are blank

    • 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
      Throws:
      NullPointerException - if globalLinks is null
      IllegalArgumentException - If globalLinks is empty
      See Also:

    • globalPackageOptions

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

      Using format:

      • matchingRegexp
      • -deprecated
      • -privateApi
      • +warnUndocumented
      • +suppress
      • +visibility:PUBLIC
      • ...
      Parameters:
      options - one or more package configurations
      Returns:
      this operation instance
      Throws:
      NullPointerException - if options is null or contain null elements
      IllegalArgumentException - if options is empty or contains blank elements

    • globalPackageOptions

      public final 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
      Throws:
      NullPointerException - if options is null or contain null elements
      IllegalArgumentException - if options is empty or contains blank elements

    • globalPackageOptions

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

    • 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
      Throws:
      NullPointerException - if links is null or contains null elements
      IllegalArgumentException - if links is empty or contains blank elements

    • globalSrcLink

      public final 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
      Throws:
      NullPointerException - if links is null
      IllegalArgumentException - if links is empty or contains null or empty elements

    • globalSrcLink

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

    • globalSuppressAnnotatedWith

      public List<String> globalSuppressAnnotatedWith()
      Retrieves the global list of annotation FQNs to suppress declarations annotated with.
      Returns:
      the annotations

    • globalSuppressAnnotatedWith

      public final DokkaOperation globalSuppressAnnotatedWith(Collection<String> annotations)
      Set the global list of annotation FQNs to suppress declarations annotated with.
      Parameters:
      annotations - the annotations
      Returns:
      this operation instance
      Throws:
      NullPointerException - if annotations is null
      IllegalArgumentException - if annotations is empty or contains null or blank elements

    • globalSuppressAnnotatedWith

      public DokkaOperation globalSuppressAnnotatedWith(String... annotations)
      Global list of annotation FQNs to suppress declarations annotated with.
      Parameters:
      annotations - one or more annotation
      Returns:
      this operation instance
      Throws:
      NullPointerException - if annotations is null or contains null elements
      IllegalArgumentException - if annoations is empty or contains blank elements

    • 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 a per-package basis.

      Parameters:
      files - one or more files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if includes is null
      IllegalArgumentException - If includes is empty
      See Also:

    • includes

      public final 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 a per-package basis.

      Parameters:
      files - the Markdown files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if files is null
      IllegalArgumentException - If files is empty
      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 a per-package basis.

      Parameters:
      files - one or more files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if files is null or contain null elements
      IllegalArgumentException - if files is empty or contains blank elements
      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 a per-package basis.

      Parameters:
      files - one or more files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if files is null
      IllegalArgumentException - If files is empty
      See Also:

    • includes

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

    • includesPaths

      public final 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 a per-package basis.

      Parameters:
      files - the Markdown files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if files is null
      IllegalArgumentException - If files is empty
      See Also:

    • includesStrings

      public final 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 a per-package basis.

      Parameters:
      files - the Markdown files
      Returns:
      this operation instance
      Throws:
      NullPointerException - if files is null or contain null elements
      IllegalArgumentException - if files is empty or contains empty elements
      See Also:

    • json

      public DokkaOperation json(Path configuration)
      JSON configuration file path.
      Parameters:
      configuration - the configuration file path
      Returns:
      this operation instance
      Throws:
      NullPointerException - if configuration is null

    • json

      public DokkaOperation json(File configuration)
      JSON configuration file path.
      Parameters:
      configuration - the configuration file path
      Returns:
      this operation instance
      Throws:
      NullPointerException - if configuration is null

    • json

      public @Nullable 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
      Returns:
      this operation instance
      Throws:
      NullPointerException - if configuration is null
      IllegalArgumentException - if configuration is blank

    • loggingLevel

      public DokkaOperation loggingLevel(LoggingLevel loggingLevel)
      Sets the logging level.
      Parameters:
      loggingLevel - the logging level
      Returns:
      this operation instance
      Throws:
      NullPointerException - if loggingLevel is null

    • 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
      Throws:
      NullPointerException - if moduleName is null
      IllegalArgumentException - if moduleName is blank

    • moduleVersion

      public DokkaOperation moduleVersion(String version)
      Set the documented version.
      Parameters:
      version - the version
      Returns:
      this operation instance
      Throws:
      NullPointerException - if version is null
      IllegalArgumentException - if version is blank

    • 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 @Nullable 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
      Throws:
      NullPointerException - if outputDir is null
      IllegalArgumentException - if outputDir is blank

    • 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
      Throws:
      NullPointerException - if outputDir is null

    • 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
      Throws:
      NullPointerException - if outputDir is null

    • outputFormat

      public @Nullable OutputFormat outputFormat()
      Retrieves the output format.
      Returns:
      the output format

    • outputFormat

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

    • 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
      Throws:
      NullPointerException - if name or jsonConfiguration is null
      IllegalArgumentException - if name or jsonConfiguration are blank

    • pluginConfigurations

      public DokkaOperation pluginConfigurations(Map<String,String> pluginConfigurations)
      Sets the configuration for Dokka plugins.
      Parameters:
      pluginConfigurations - the map of configurations
      Returns:
      this operation instance
      Throws:
      NullPointerException - if pluginConfigurations is null or contain null elements
      IllegalArgumentException - If pluginConfigurations is empty or contains empty elements
      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
      Throws:
      NullPointerException - if jars is null
      IllegalArgumentException - If jars is empty
      See Also:

    • pluginsClasspath

      public final DokkaOperation pluginsClasspath(Collection<File> jars)
      Sets the jars for Dokka plugins and their dependencies.
      Parameters:
      jars - the jars
      Returns:
      this operation instance
      Throws:
      NullPointerException - if jars is null
      IllegalArgumentException - If jars is empty
      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
      Throws:
      NullPointerException - if jars is null or contain null elements
      IllegalArgumentException - if jars is empty or contains blank elements
      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
      Throws:
      NullPointerException - if jars is null or contain null elements
      IllegalArgumentException - if jars is empty or contains empty elements
      See Also:

    • pluginsClasspath

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

    • pluginsClasspathPaths

      public final DokkaOperation pluginsClasspathPaths(Collection<Path> jars)
      Sets the jars for Dokka plugins and their dependencies.
      Parameters:
      jars - the jars
      Returns:
      this operation instance
      Throws:
      NullPointerException - if jars is null
      IllegalArgumentException - If jars is empty
      See Also:

    • pluginsClasspathStrings

      public final DokkaOperation pluginsClasspathStrings(Collection<String> jars)
      Sets the jars for Dokka plugins and their dependencies.
      Parameters:
      jars - the jars
      Returns:
      this operation instance
      Throws:
      NullPointerException - if jars is null
      IllegalArgumentException - If jars is empty
      See Also:

    • sourceSet

      public SourceSet sourceSet()
      Returns the configurations for the source set.
      Returns:
      the source ser configuration

    • 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
      Throws:
      NullPointerException - if sourceSet is null

    • 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