tidy up docs/comments, task config

adamko-dev · Jan 13, 2024 · a3940b8 · a3940b8
1 parent a98e0bf
commit a3940b8
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 30 deletions.
diff --git a/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt b/modules/dokkatoo-plugin/src/main/kotlin/DokkatooBasePlugin.kt
@@ -72,19 +72,30 @@ constructor(
       sourceSetScopeConvention = dokkatooExtension.sourceSetScopeDefault
     )
 
-    target.tasks.withType<DokkatooGenerateTask>().configureEach {
-      cacheDirectory.convention(dokkatooExtension.dokkatooCacheDirectory)
-      workerLogFile.convention(temporaryDir.resolve("dokka-worker.log"))
-      dokkaConfigurationJsonFile.convention(temporaryDir.resolve("dokka-configuration.json"))
-    }
-
     target.tasks.withType<DokkatooPrepareModuleDescriptorTask>().configureEach {
       moduleName.convention(dokkatooExtension.moduleName)
       includes.from(providers.provider { dokkatooExtension.dokkatooSourceSets.flatMap { it.includes } })
       modulePath.convention(dokkatooExtension.modulePath)
     }
 
     target.tasks.withType<DokkatooGenerateTask>().configureEach {
+      cacheDirectory.convention(dokkatooExtension.dokkatooCacheDirectory)
+      workerLogFile.convention(temporaryDir.resolve("dokka-worker.log"))
+      dokkaConfigurationJsonFile.convention(temporaryDir.resolve("dokka-configuration.json"))
+
+      workerLogFile.convention(temporaryDir.resolve("dokka-worker.log"))
+      workerIsolation.convention(ProcessIsolation {
+        debug.convention(false)
+        jvmArgs.convention(
+          listOf(
+            //"-XX:MaxMetaspaceSize=512m",
+            "-XX:+HeapDumpOnOutOfMemoryError",
+            "-XX:+AlwaysPreTouch", // https://github.com/gradle/gradle/issues/3093#issuecomment-387259298
+            //"-XX:StartFlightRecording=disk=true,name={path.drop(1).map { if (it.isLetterOrDigit()) it else '-' }.joinToString("")},dumponexit=true,duration=30s",
+            //"-XX:FlightRecorderOptions=repository=$baseDir/jfr,stackdepth=512",
+          )
+        )
+      })
 
       publicationEnabled.convention(true)
       onlyIf("publication must be enabled") { publicationEnabled.getOrElse(true) }
@@ -99,22 +110,6 @@ constructor(
       generator.dokkaSourceSets.configureDefaults(
         sourceSetScopeConvention = dokkatooExtension.sourceSetScopeDefault
       )
-
-      workerLogFile.convention(temporaryDir.resolve("dokka-worker.log"))
-//      workerIsolation.convention(ProcessIsolation {
-//        debug.convention(false)
-//        jvmArgs.convention(
-//          listOf(
-//            //"-XX:MaxMetaspaceSize=512m",
-//            "-XX:+HeapDumpOnOutOfMemoryError",
-//            "-XX:+AlwaysPreTouch", // https://github.com/gradle/gradle/issues/3093#issuecomment-387259298
-//            //"-XX:StartFlightRecording=disk=true,name={path.drop(1).map { if (it.isLetterOrDigit()) it else '-' }.joinToString("")},dumponexit=true,duration=30s",
-//            //"-XX:FlightRecorderOptions=repository=$baseDir/jfr,stackdepth=512",
-//          )
-//        )
-//      })
-      // TODO setting classloader isolation causes many test failures due to metaspace limits.
-      workerIsolation.set(ClassLoaderIsolation())
     }
 
     dokkatooExtension.dokkatooSourceSets.configureDefaults(

diff --git a/modules/dokkatoo-plugin/src/main/kotlin/tasks/DokkatooGenerateTask.kt b/modules/dokkatoo-plugin/src/main/kotlin/tasks/DokkatooGenerateTask.kt
@@ -75,6 +75,35 @@ constructor(
   @get:Nested
   val generator: DokkaGeneratorParametersSpec = objects.newInstance(pluginsConfiguration)
 
+  /**
+   * Dokkatoo runs Dokka Generator in a separate
+   * [Gradle Worker](https://docs.gradle.org/8.5/userguide/worker_api.html).
+   *
+   * You can control whether Dokkatoo launches Dokka Generator in
+   * * a new process, using [ProcessIsolation],
+   * * or the current process with an isolated classpath, using [ClassLoaderIsolation].
+   *
+   * _Aside: Launching [without isolation][WorkerExecutor.noIsolation] is not an option, because
+   * Dokka **requires** an isolated classpath._
+   *
+   * ```kotlin
+   * dokkatoo {
+   *   // use the current Gradle process, but with an isolated classpath
+   *   workerIsolation = ClassLoaderIsolation()
+   *
+   *   // launch a new process, optionally controlling the standard JVM options
+   *   workerIsolation = ProcessIsolation {
+   *     minHeapSize = "2g" // increase minimum heap size
+   *     systemProperties.add("someCustomProperty", 123)
+   *   }
+   * }
+   * ```
+   *
+   * @see WorkerIsolation
+   * @see dev.adamko.dokkatoo.workers.ProcessIsolation
+   * @see dev.adamko.dokkatoo.workers.ClassLoaderIsolation
+   *
+   */
   @get:Nested
   abstract val workerIsolation: Property<WorkerIsolation>
 
@@ -89,7 +118,7 @@ constructor(
   /**
    * Create a new [ProcessIsolation] options.
    *
-   * The resulting options must be set into [workerIsolation].
+   * The resulting options instance must be set into [workerIsolation].
    */
   fun ProcessIsolation(configure: ProcessIsolation.() -> Unit = {}): ProcessIsolation =
     objects.newInstance<ProcessIsolation>().apply {
@@ -214,19 +243,19 @@ constructor(
   //region Deprecated Properties
   /** @see JavaForkOptions.getDebug */
   @get:Internal
-  @Deprecated("moved to TODO") // TODO
+  @Deprecated("worker options were moved to `workerIsolation` property to allow for configuring worker isolation")
   abstract val workerDebugEnabled: Property<Boolean>
   /** @see JavaForkOptions.getMinHeapSize */
   @get:Internal
-  @Deprecated("moved to TODO") // TODO
+  @Deprecated("worker options were moved to `workerIsolation` property to allow for configuring worker isolation")
   abstract val workerMinHeapSize: Property<String>
   /** @see JavaForkOptions.getMaxHeapSize */
   @get:Internal
-  @Deprecated("moved to TODO") // TODO
+  @Deprecated("worker options were moved to `workerIsolation` property to allow for configuring worker isolation")
   abstract val workerMaxHeapSize: Property<String>
   /** @see JavaForkOptions.jvmArgs */
   @get:Internal
-  @Deprecated("moved to TODO") // TODO
+  @Deprecated("worker options were moved to `workerIsolation` property to allow for configuring worker isolation")
   abstract val workerJvmArgs: ListProperty<String>
   //endregion
 }
diff --git a/modules/dokkatoo-plugin/src/main/kotlin/workers/WorkerIsolationProperties.kt b/modules/dokkatoo-plugin/src/main/kotlin/workers/WorkerIsolationProperties.kt
@@ -6,32 +6,41 @@ import org.gradle.api.provider.Property
 import org.gradle.api.tasks.Input
 import org.gradle.api.tasks.Optional
 import org.gradle.process.JavaForkOptions
+import org.gradle.workers.WorkerExecutor
 
 
 /**
  * Configure how a Gradle Worker is created using [org.gradle.workers.WorkerExecutor].
+ *
+ * @see WorkerExecutor.classLoaderIsolation
+ * @see WorkerExecutor.processIsolation
  */
 sealed interface WorkerIsolation
 
 
 /**
- * Create a Worker in the current Gradle process, with an isolated classpath.
+ * Execute a Worker in the current Gradle process, with an
+ * [isolated classpath][WorkerExecutor.classLoaderIsolation].
  *
  * Presently there are no options to configure the behaviour of a classloader-isolated worker.
  *
  * @see org.gradle.workers.ClassLoaderWorkerSpec
+ * @see WorkerExecutor.classLoaderIsolation
  */
 interface ClassLoaderIsolation : WorkerIsolation {
   // no options yet...
 }
 
 
 /**
- * Create a Worker using process isolation.
+ * Create a Worker using [process isolation][WorkerExecutor.processIsolation].
  *
- * Gradle will launch new Java process specifically for Dokka.
+ * Gradle will launch
+ * [new Worker Daemon](https://docs.gradle.org/8.5/userguide/worker_api.html#creating_a_worker_daemon)
+ * re-using it across builds.
  *
  * @see org.gradle.workers.ProcessWorkerSpec
+ * @see WorkerExecutor.processIsolation
  */
 interface ProcessIsolation : WorkerIsolation {
   /** @see JavaForkOptions.setDebug */